@servicenow/sdk-build-core 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * as ts from 'ts-morph';
+export * from './util';
+export * from './TypeScript';
+export * from './XML';
+export * from './plugins';
+export * from './GUID';
+export * from './Keys';
+export * from './BuildOptions';

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ts = void 0;
+exports.ts = __importStar(require("ts-morph"));
+__exportStar(require("./util"), exports);
+__exportStar(require("./TypeScript"), exports);
+__exportStar(require("./XML"), exports);
+__exportStar(require("./plugins"), exports);
+__exportStar(require("./GUID"), exports);
+__exportStar(require("./Keys"), exports);
+__exportStar(require("./BuildOptions"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAA8B;AAC9B,yCAAsB;AACtB,+CAA4B;AAC5B,wCAAqB;AACrB,4CAAyB;AACzB,yCAAsB;AACtB,yCAAsB;AACtB,iDAA8B"}

package/dist/plugins/Context.d.ts

@@ -0,0 +1,198 @@
+import * as ts from 'ts-morph';
+import { Document, File, LinkedDocument, UnlinkedDocument, Xml, XmlData, EntityData, Arranged, DocumentMap, ExtractionResult } from './behaviors';
+import { Keys } from '../Keys';
+import { Plugin } from './Plugin';
+import { FluentDiagnostic } from './Diagnostic';
+import { ProjectContext } from '@servicenow/sdk-project';
+import type { Diagnostic } from '@servicenow/sdk-project';
+import type { Data } from './behaviors';
+/**
+ * The context object is a collection of contextual information and methods
+ * passed into all the various behaviors of a plugin when those behaviors are
+ * invoked. It is also used by the build system to orchestrate the build.
+ *
+ * Each behavioral method on the context can accept an array of plugins as
+ * an argument to control which plugins are used for that request. If no
+ * plugins are provided as input, all available plugins will be used.
+ */
+export type Context = ProjectContext & {
+    /**
+     * Accepts a parsed XML object and returns an array of {@linkcode XmlData}
+     * extracted from that object.
+     *
+     * @see {@linkcode Extractors}
+     * @param xml The parsed XML to extract.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns an array of extracted data.
+     */
+    extractXml(this: Context, xml: Xml, plugins?: Plugin[]): XmlData[];
+    /**
+     * Accepts an AST node and returns a result containing an array of
+     * {@linkcode RawData} or {@linkcode EntityData} extracted from that node.
+     *
+     * @see {@linkcode Extractors}
+     * @param node The node to extract.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a result object containing an array of extracted data.
+     */
+    extractAst(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult;
+    /**
+     * Accepts an AST node and returns a result containing an array of
+     * {@linkcode RawData} extracted from that node.
+     *
+     * @see {@linkcode Extractors}
+     * @param node The node to extract.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a result object containing an array of extracted data.
+     */
+    extractRaw(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult<Data>;
+    /**
+     * Accepts an AST node and returns a result containing an array of
+     * {@linkcode EntityData} extracted from that node.
+     *
+     * @see {@linkcode Extractors}
+     * @param node The node to extract.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a result object containing an array of extracted entities.
+     */
+    extractEntities(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult<EntityData>;
+    /**
+     * Accepts an array of entity data and returns a {@linkcode LinkedDocument}
+     * array.
+     *
+     * @see {@linkcode Composers}
+     * @param data The {@linkcode EntityData} to compose.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a {@linkcode LinkedDocument} array.
+     */
+    composeEntities(this: Context, data: EntityData[], plugins?: Plugin[]): LinkedDocument[];
+    /**
+     * Accepts an array of XML data and returns an {@linkcode UnlinkedDocument}
+     * array.
+     *
+     * @see {@linkcode Composers}
+     * @param data The {@linkcode XmlData} to compose.
+     * @param context The {@linkcode Context} object.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns an {@linkcode UnlinkedDocument} array.
+     */
+    composeXml(this: Context, data: XmlData[], plugins?: Plugin[]): UnlinkedDocument[];
+    /**
+     * Accepts an array of documents and returns the same documents
+     * as unresolved arranged documents.
+     *
+     * @see {@linkcode Arrangers}
+     * @param documents The {@linkcode Document}s to arrange.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a {@linkcode Document} & {@linkcode Arranged} array.
+     */
+    arrange(this: Context, documents: Document[], plugins?: Plugin[]): (Document & Arranged<'unresolved'>)[];
+    /**
+     * Accepts an array of documents and returns an array of files.
+     *
+     * @see {@linkcode Serializers}
+     * @param documents The {@linkcode Document}s to serialize.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a {@linkcode File} array.
+     */
+    serialize(this: Context, documents: (Document & Arranged)[], plugins?: Plugin[]): File[];
+    /**
+     * Accepts an array of documents, generates new AST nodes for those
+     * documents, and returns the same documents as linked documents.
+     *
+     * @see {@linkcode Generators}
+     * @param documents The {@linkcode Document}s to generate AST nodes for.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns a {@linkcode LinkedDocument} array.
+     */
+    generate(this: Context, documents: (UnlinkedDocument & Arranged)[], plugins?: Plugin[]): LinkedDocument[];
+    /**
+     * Accepts an array of linked documents and performs transformations on
+     * their original nodes to reflect any changes that may have been made to
+     * those documents' data.
+     *
+     * @see {@linkcode Transformers}
+     * @param documents The {@linkcode LinkedDocument}s to transform.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     */
+    transform(this: Context, documents: (LinkedDocument & Arranged)[], plugins?: Plugin[]): void;
+    /**
+     * Accepts an array of extracted entities and runs post-processors on that
+     * data. Post-processors may perform a variety of arbitrary operations.
+     *
+     * @see {@linkcode PostProcessors}
+     * @param data The {@linkcode EntityData} to process.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     */
+    postProcessEntities(this: Context, data: EntityData[], plugins?: Plugin[]): void;
+    /**
+     * Accepts an AST node and returns an array of {@linkcode FluentDiagnostic}s
+     * for that node.
+     *
+     * @see {@linkcode Diagnostics}
+     * @param node The node to get diagnostics for.
+     * @param plugins An optional array of {@linkcode Plugin}s to use.
+     * @returns an array of diagnostics.
+     */
+    getAstDiagnostics(this: Context, node: ts.Node, plugins?: Plugin[]): FluentDiagnostic[];
+    /**
+     * An object with metadata related to plugin like list of all tables that are claimed to be handled by a specific plugin, and
+     * the level of enforcement they apply to that table
+     * and API that the plugin is responsible for.
+     */
+    getPluginForTable(table: string): {
+        logLevel: Diagnostic.Level;
+        api: string;
+    } | undefined;
+    /**
+     * Indicates whether or not the build system is running in debug mode. This
+     * should be checked before printing verbose log messages.
+     */
+    debug: boolean;
+    /**
+     * Indicates the current mode in which the build system is running.
+     */
+    mode: 'serialize' | 'transform';
+    /**
+     * An array of plugins that will be used (unless overridden) during various
+     * build process operations.
+     *
+     * @see {@link Plugin}
+     */
+    plugins: Plugin[];
+    /**
+     * An array of plugins which implement entity-handling behaviors which will
+     * be used during various build process operations. These plugins are always
+     * executed BEFORE the plugins in the {@link Context#plugins} array.
+     *
+     * @see {@link Plugin}
+     */
+    entityPlugins: Plugin[];
+    /**
+     * Record to store and access data across plugins
+     */
+    store: Record<string, unknown>;
+    usageCount: {
+        [key: string]: number;
+    };
+    /**
+     * Resets the store to initial state
+     */
+    resetStore(): void;
+    /**
+     * An object of XML file names that was marked as handled or ignored by code transformation during the build process.
+     */
+    handledXmls: Record<string, HandledStates>;
+    setAllDocuments: (documents: Document[]) => void;
+    getAllDocuments: () => Document[];
+    getDocumentMap: () => DocumentMap;
+    getDocument: (sysId: string, kind?: string) => Document | undefined;
+    /**
+     * @deprecated Use the key methods on the context object instead.
+     */
+    keys: Keys;
+    registerExplicitId: Keys['registerExplicitId'];
+    registerCompositeId: Keys['registerCompositeId'];
+    getDeletedAndUnusedIds: Keys['getDeletedAndUnusedIds'];
+};
+export type HandledStates = 'handled' | 'ignored' | 'skipped' | 'unchanged';

package/dist/plugins/Context.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Context.js.map

package/dist/plugins/Context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.js","sourceRoot":"","sources":["../../src/plugins/Context.ts"],"names":[],"mappings":""}

package/dist/plugins/Diagnostic.d.ts

@@ -0,0 +1,10 @@
+import * as ts from 'ts-morph';
+import { Diagnostic } from '@servicenow/sdk-project';
+export declare class FluentDiagnostic extends Diagnostic {
+    constructor(node: ts.Node, message: string, { level, code }?: {
+        level?: Diagnostic.Level;
+        code?: number;
+    });
+    asTypeScriptDiagnostic(): ts.ts.Diagnostic;
+}
+export declare function findObjectPropertyValue(callExpression: ts.CallExpression, field: string): ts.Expression<ts.ts.Expression>;

package/dist/plugins/Diagnostic.js

@@ -0,0 +1,52 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FluentDiagnostic = void 0;
+exports.findObjectPropertyValue = findObjectPropertyValue;
+const ts = __importStar(require("ts-morph"));
+const sdk_project_1 = require("@servicenow/sdk-project");
+class FluentDiagnostic extends sdk_project_1.Diagnostic {
+    constructor(node, message, { level = sdk_project_1.Diagnostic.Level.Error, code = node.getKind() } = {}) {
+        super(message, node.getSourceFile(), { start: node.getStart(), end: node.getEnd() }, code, 'fluent', level);
+    }
+    asTypeScriptDiagnostic() {
+        return {
+            messageText: this.message,
+            category: sdk_project_1.Diagnostic.Level.toCategory(this.level),
+            code: this.code,
+            file: this.file.compilerNode,
+            start: this.position.start,
+            length: this.position.end - this.position.start,
+        };
+    }
+}
+exports.FluentDiagnostic = FluentDiagnostic;
+function findObjectPropertyValue(callExpression, field) {
+    const property = callExpression
+        .getFirstDescendantByKind(ts.SyntaxKind.ObjectLiteralExpression)
+        ?.getProperty(field);
+    return property?.getInitializer() || callExpression;
+}
+//# sourceMappingURL=Diagnostic.js.map

package/dist/plugins/Diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagnostic.js","sourceRoot":"","sources":["../../src/plugins/Diagnostic.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,0DAMC;AA9BD,6CAA8B;AAC9B,yDAAoD;AAEpD,MAAa,gBAAiB,SAAQ,wBAAU;IAC5C,YACI,IAAa,EACb,OAAe,EACf,EAAE,KAAK,GAAG,wBAAU,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,KAAkD,EAAE;QAE3G,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAA;IAC/G,CAAC;IAEe,sBAAsB;QAClC,OAAO;YACH,WAAW,EAAE,IAAI,CAAC,OAAO;YACzB,QAAQ,EAAE,wBAAU,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;YACjD,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY;YAC5B,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK;YAC1B,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK;SAClD,CAAA;IACL,CAAC;CACJ;AAnBD,4CAmBC;AAED,SAAgB,uBAAuB,CAAC,cAAiC,EAAE,KAAa;IACpF,MAAM,QAAQ,GAAG,cAAc;SAC1B,wBAAwB,CAAC,EAAE,CAAC,UAAU,CAAC,uBAAuB,CAAC;QAChE,EAAE,WAAW,CAAC,KAAK,CAA0B,CAAA;IAEjD,OAAO,QAAQ,EAAE,cAAc,EAAE,IAAI,cAAc,CAAA;AACvD,CAAC"}

package/dist/plugins/Plugin.d.ts

@@ -0,0 +1,175 @@
+import { SupportedKindName } from '@servicenow/sdk-project';
+import { Extractors, Composers, Serializers, Transformers, Generators, Arrangers, PostProcessors, Diagnostics, TableOwnership } 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, RawNodeKinds extends SupportedKindName = any, EntityNodeKinds 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<RawNodeKinds, EntityNodeKinds>;
+    /**
+     * 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 declare function Plugin<const DiagnosticsNodeKinds extends SupportedKindName | 'Node', const RawNodeKinds extends SupportedKindName, const EntityNodeKinds extends SupportedKindName, const SerializerDocumentKinds extends string, const GeneratorDocumentKinds extends string, const TransformerDocumentKinds extends string, const P extends Plugin<DiagnosticsNodeKinds, RawNodeKinds, EntityNodeKinds, SerializerDocumentKinds, GeneratorDocumentKinds, TransformerDocumentKinds>>(plugin: P & Plugin<DiagnosticsNodeKinds, RawNodeKinds, EntityNodeKinds, SerializerDocumentKinds, GeneratorDocumentKinds, TransformerDocumentKinds>): P;

package/dist/plugins/Plugin.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Plugin = Plugin;
+/**
+ * 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
+ */
+function Plugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=Plugin.js.map

package/dist/plugins/Plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.js","sourceRoot":"","sources":["../../src/plugins/Plugin.ts"],"names":[],"mappings":";;AA0NA,wBA2BC;AAnCD;;;;;;;GAOG;AACH,SAAgB,MAAM,CAgBlB,MAQK;IAEL,OAAO,MAAW,CAAA;AACtB,CAAC"}

package/dist/plugins/behaviors/Arranger.d.ts

@@ -0,0 +1,26 @@
+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;
+};
+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>;
+/**
+ * @see {@linkcode Plugin#arrangers}
+ */
+export type Arrangers<DocumentKinds extends string = string> = {
+    [K in DocumentKinds]: ArrangerFunction<K>;
+};

package/dist/plugins/behaviors/Arranger.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Arranger.js.map

package/dist/plugins/behaviors/Arranger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Arranger.js","sourceRoot":"","sources":["../../../src/plugins/behaviors/Arranger.ts"],"names":[],"mappings":""}

package/dist/plugins/behaviors/Composer.d.ts

@@ -0,0 +1,101 @@
+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;
+    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 = {
+    [kinds: string]: {
+        [guids: string]: Document;
+    };
+};
+/**
+ * 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) => 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;
+/**
+ * @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 declare function linkDocument<const K extends string, const N extends SupportedNode>(document: UnlinkedDocument<K>, node: N): LinkedDocument<K, N>;