@komaci/common-shared 240.1.3

package/build/komaciDocumentIntrospection.d.ts

@@ -0,0 +1,120 @@
+import { ClassPropertyContext, ClassPropertyContexts, ImportPropertyContext, InputTraversalCallback, PropertyTypes, WirePropertyContext } from './types';
+import { FunctionType, FunctionReference, KomaciDocument, Property, Import, Adg, Value, Composition, ComposedAdg, Iteration, Binding, Image, PrimitiveValue } from '@komaci/types';
+/**
+ * Check if the composition is an Iteration
+ * @param composition composition obj to check
+ * @returns if composition is an Iteration
+ */
+export declare function isCompositionAnIteration(composition: Composition): composition is Iteration;
+/**
+ * Check if the composition is a ComposedAdg
+ * @param composition composition obj to check
+ * @returns if composition is a ComposedAdg
+ */
+export declare function isCompositionAComposedAdg(composition: Composition): composition is ComposedAdg;
+/**
+ * Type guard: Check if the given Composition is an Image
+ * @param {Composition} composition the compositions whose type we will check
+ * @returns {boolean} true if this Composition is an Image, false if not
+ */
+export declare function isCompositionAnImage(composition: Composition): composition is Image;
+/**
+ * Type guard: Check if the given src attribute is a PrimitiveValue
+ * @param {PrimitiveValue | Binding} src the attribute whose type we will check
+ * @returns {boolean} true if the input attribute was a PrimitiveValue, false if it is not
+ */
+export declare function isSrcPrimitiveValue(src: PrimitiveValue | Binding): src is PrimitiveValue;
+/**
+ * Type guard: Check if the given src attribute is a Binding
+ * @param {Binding | PrimitiveValue} src the attribute whose type we will check
+ * @returns {boolean} true if the input attribute was a Binding, false if it was a Primitive Value
+ */
+export declare function isSrcABinding(src: Binding | PrimitiveValue): src is Binding;
+/**
+ * Check if input is a Function reference
+ * @param node input to check
+ * @returns if it is a function reference
+ */
+export declare function isFunctionReference(node: Property['input']): node is FunctionReference;
+/**
+ * Confirm if a function object is of a specfic type
+ * @param type The type to validate against
+ * @param detail the property detail that references the function
+ * @param functions The function array to look in for the referenced function
+ * @returns If the referenced function matches the provided type
+ */
+export declare function isAFunctionOfType(type: string, detail: Property, functions?: FunctionType[]): boolean;
+/**
+ * Helper to check if a referenced import in a Komaci Doc is defined
+ * @param importIndex The import index to view
+ * @param nameIndex The index in the names key of an import to view
+ * @param imports The full array of import objects
+ * @returns if it is good or not
+ */
+export declare function isImportValid(importIndex: number, nameIndex: number, imports?: Import[]): boolean;
+/**
+ * In Komaci Documents, if a value is referenced like record.data.key, it shows up as record/data/key.
+ * record is the property we care about so if we are in one of these cases we want to strip off everything after the slash
+ * @param value
+ * @returns
+ */
+export declare function stripChildReferenceFromValue(value: string): string;
+/**
+ * Inflate a map with Class Property metadata in the most generic way possible so later we can update as needed.
+ *
+ * This function along with collectPropertyMetadataFromScriptDoc and updatePropertyMetadataFromTemplateDoc can be
+ * called in sequence to get all the needful data about properties for a given set of komaci documents. Currently
+ * consumed directly in modGenScript and static-analyzer so check to see if this has already been called
+ * before calling it
+ *
+ * @param component The component ADG to process
+ * @param doc The full komaci doc we are looking in
+ * @returns The inflated properties map
+ */
+export declare function initializePropertiesMap(component: Adg, doc: KomaciDocument, properties: ClassPropertyContexts): ClassPropertyContexts;
+/**
+ * Traverse the input of a Function object (as definged in a Komaci Document) generically. When we get to a specific value
+ * in the tree, we run the provided callback. The callback can return `true` if we should stop
+ * traversal down this path.
+ *
+ * @param input Function Input
+ * @param cb Callback to trigger for any "Real" value
+ * @param key Sometimes as we go through the tree, a real value will be mapped to some key in a higher
+ *            context so we make that available in case consumers need it
+ * @returns If we have stopped traversal down this path
+ */
+export declare function traverseInput(input: Value | Value[], cb: InputTraversalCallback, key?: string): boolean;
+export declare function traverseParentAdgs(component: Adg, doc: KomaciDocument, cb: (component: Adg) => void): void;
+/**
+ * Traverse the Komaci Document for a script file and collect property usages.
+ *
+ * This function:
+ * 1. prepares the properties object with initial values
+ * 2. collects usages of properties from wire functions
+ * @param doc Komaci Script Doc to traverse
+ * @returns contextual information about properties
+ */
+export declare function collectPropertyMetadataFromScriptDoc(doc: KomaciDocument): ClassPropertyContexts;
+/**
+ * Recursively probe a composition and it's children for usages of properties.
+ * @param composition Current composition
+ * @param properties The map of properties to update
+ */
+export declare function updatePropertiesForComposition(composition: Composition, properties: ClassPropertyContexts): void;
+/**
+ * Collect usages of properties from compositions in a Komaci Template Document
+ * @param doc Komaci Document
+ * @param properties The current map of properties, this is just updating them.
+ */
+export declare function updatePropertyMetadataFromTemplateDoc(doc: KomaciDocument, properties: ClassPropertyContexts): void;
+/**
+ * Updates used properties to record whether they were used in Priming.
+ * @param prop the name of the getter under consideration
+ * @param identifiers list of member identifiers used in getters
+ * @param properties Map for all class properties and their basic, KomaciDoc analyzable metadata.
+ * @param type The property type so we can make sure the metadata has the right value
+ */
+export declare function updatePropertyUsage(prop: string, identifiers: string[], properties: ClassPropertyContexts, type: PropertyTypes): void;
+export declare function isPropertyAWire(property: ClassPropertyContext): property is WirePropertyContext;
+export declare function isPropertyFromImport(property: ClassPropertyContext): property is ImportPropertyContext;
+//# sourceMappingURL=komaciDocumentIntrospection.d.ts.map

package/build/komaciDocumentIntrospection.js

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPropertyFromImport = exports.isPropertyAWire = exports.updatePropertyUsage = exports.updatePropertyMetadataFromTemplateDoc = exports.updatePropertiesForComposition = exports.collectPropertyMetadataFromScriptDoc = exports.traverseParentAdgs = exports.traverseInput = exports.initializePropertiesMap = exports.stripChildReferenceFromValue = exports.isImportValid = exports.isAFunctionOfType = exports.isFunctionReference = exports.isSrcABinding = exports.isSrcPrimitiveValue = exports.isCompositionAnImage = exports.isCompositionAComposedAdg = exports.isCompositionAnIteration = void 0;
+const types_1 = require("./types");
+/**
+ * Check if the composition is an Iteration
+ * @param composition composition obj to check
+ * @returns if composition is an Iteration
+ */
+function isCompositionAnIteration(composition) {
+    return composition?.type === 'Iteration';
+}
+exports.isCompositionAnIteration = isCompositionAnIteration;
+/**
+ * Check if the composition is a ComposedAdg
+ * @param composition composition obj to check
+ * @returns if composition is a ComposedAdg
+ */
+function isCompositionAComposedAdg(composition) {
+    return composition?.type === 'ComposedAdg';
+}
+exports.isCompositionAComposedAdg = isCompositionAComposedAdg;
+/**
+ * Type guard: Check if the given Composition is an Image
+ * @param {Composition} composition the compositions whose type we will check
+ * @returns {boolean} true if this Composition is an Image, false if not
+ */
+function isCompositionAnImage(composition) {
+    return composition?.type === 'Image';
+}
+exports.isCompositionAnImage = isCompositionAnImage;
+/**
+ * Type guard: Check if the given src attribute is a PrimitiveValue
+ * @param {PrimitiveValue | Binding} src the attribute whose type we will check
+ * @returns {boolean} true if the input attribute was a PrimitiveValue, false if it is not
+ */
+function isSrcPrimitiveValue(src) {
+    return src.type === 'PrimitiveValue';
+}
+exports.isSrcPrimitiveValue = isSrcPrimitiveValue;
+/**
+ * Type guard: Check if the given src attribute is a Binding
+ * @param {Binding | PrimitiveValue} src the attribute whose type we will check
+ * @returns {boolean} true if the input attribute was a Binding, false if it was a Primitive Value
+ */
+function isSrcABinding(src) {
+    return src.type === 'Binding' && typeof src.value === 'string';
+}
+exports.isSrcABinding = isSrcABinding;
+/**
+ * Check if input is a Function reference
+ * @param node input to check
+ * @returns if it is a function reference
+ */
+function isFunctionReference(node) {
+    return node?.type === 'FunctionReference';
+}
+exports.isFunctionReference = isFunctionReference;
+/**
+ * Confirm if a function object is of a specfic type
+ * @param type The type to validate against
+ * @param detail the property detail that references the function
+ * @param functions The function array to look in for the referenced function
+ * @returns If the referenced function matches the provided type
+ */
+function isAFunctionOfType(type, detail, functions) {
+    return (isFunctionReference(detail.input) &&
+        functions?.[detail.input.value]?.type === type);
+}
+exports.isAFunctionOfType = isAFunctionOfType;
+/**
+ * Helper to check if a referenced import in a Komaci Doc is defined
+ * @param importIndex The import index to view
+ * @param nameIndex The index in the names key of an import to view
+ * @param imports The full array of import objects
+ * @returns if it is good or not
+ */
+function isImportValid(importIndex, nameIndex, imports) {
+    return imports?.[importIndex]?.names?.[nameIndex] !== undefined;
+}
+exports.isImportValid = isImportValid;
+/**
+ * In Komaci Documents, if a value is referenced like record.data.key, it shows up as record/data/key.
+ * record is the property we care about so if we are in one of these cases we want to strip off everything after the slash
+ * @param value
+ * @returns
+ */
+function stripChildReferenceFromValue(value) {
+    let result = value;
+    const index = value.indexOf('/');
+    if (index !== -1) {
+        result = value.substring(0, index);
+    }
+    return result;
+}
+exports.stripChildReferenceFromValue = stripChildReferenceFromValue;
+/**
+ * Inflate a map with Class Property metadata in the most generic way possible so later we can update as needed.
+ *
+ * This function along with collectPropertyMetadataFromScriptDoc and updatePropertyMetadataFromTemplateDoc can be
+ * called in sequence to get all the needful data about properties for a given set of komaci documents. Currently
+ * consumed directly in modGenScript and static-analyzer so check to see if this has already been called
+ * before calling it
+ *
+ * @param component The component ADG to process
+ * @param doc The full komaci doc we are looking in
+ * @returns The inflated properties map
+ */
+function initializePropertiesMap(component, doc, properties) {
+    if (component.properties) {
+        for (const [name, detail] of Object.entries(component.properties)) {
+            const property = {
+                usedInPriming: false,
+                type: types_1.PropertyTypes.INTERNAL,
+            };
+            if (detail.isPublic) {
+                property.type = types_1.PropertyTypes.PUBLIC;
+            }
+            else if (isAFunctionOfType('WireFunction', detail, component.functions) &&
+                doc.imports) {
+                //ts rules and this is how types work ig
+                const functionDetail = component.functions?.[detail.input.value];
+                if (functionDetail) {
+                    const importIndex = parseInt(functionDetail.reference.value.charAt(0));
+                    const nameIndex = parseInt(functionDetail?.reference.value.charAt(functionDetail?.reference.value.length - 1));
+                    if (isImportValid(importIndex, nameIndex, doc.imports)) {
+                        property.type = types_1.PropertyTypes.WIRE;
+                        property.usedInPriming = true;
+                        property.wire = {
+                            name: doc.imports[importIndex].names[nameIndex],
+                            resourceName: doc.imports[importIndex].resourceName,
+                            komaciDocImportRef: functionDetail.reference.value,
+                        };
+                    }
+                }
+            }
+            if (detail.initial?.type === 'ImportReference' && doc.imports) {
+                const importIndex = parseInt(detail.initial.value.charAt(0));
+                const nameIndex = parseInt(detail.initial.value.charAt(detail.initial.value.length - 1));
+                if (isImportValid(importIndex, nameIndex, doc.imports)) {
+                    property.imports = {
+                        [detail.initial.value]: {
+                            name: doc.imports[importIndex].names[nameIndex],
+                            resourceName: doc.imports[importIndex].resourceName,
+                            komaciDocImportRef: detail.initial.value,
+                        },
+                    };
+                }
+            }
+            else if (detail.initial && doc.imports) {
+                const imports = {};
+                let totalImportRefs = 0;
+                traverseInput(detail.initial, (potentialImportRef) => {
+                    if (potentialImportRef.type === 'ImportReference') {
+                        totalImportRefs++;
+                        const importIndex = parseInt(potentialImportRef.value.charAt(0));
+                        const nameIndex = parseInt(potentialImportRef.value.charAt(potentialImportRef.value.length - 1));
+                        if (doc.imports &&
+                            isImportValid(importIndex, nameIndex, doc.imports)) {
+                            imports[potentialImportRef.value] = {
+                                name: doc.imports[importIndex].names[nameIndex],
+                                resourceName: doc.imports[importIndex].resourceName,
+                                komaciDocImportRef: potentialImportRef.value,
+                            };
+                        }
+                    }
+                    return false;
+                });
+                if (totalImportRefs !== 0) {
+                    property.imports = imports;
+                }
+            }
+            properties.set(name, property);
+        }
+    }
+    return properties;
+}
+exports.initializePropertiesMap = initializePropertiesMap;
+/**
+ * Traverse the input of a Function object (as definged in a Komaci Document) generically. When we get to a specific value
+ * in the tree, we run the provided callback. The callback can return `true` if we should stop
+ * traversal down this path.
+ *
+ * @param input Function Input
+ * @param cb Callback to trigger for any "Real" value
+ * @param key Sometimes as we go through the tree, a real value will be mapped to some key in a higher
+ *            context so we make that available in case consumers need it
+ * @returns If we have stopped traversal down this path
+ */
+function traverseInput(input, cb, key) {
+    let shouldEarlyExit = false;
+    if (!Array.isArray(input) &&
+        !(input.type === 'ArrayValue' || input.type === 'ObjectValue')) {
+        shouldEarlyExit = cb(input, key);
+    }
+    else if (Array.isArray(input)) {
+        let i = 0;
+        while (!shouldEarlyExit && i < input.length) {
+            shouldEarlyExit = traverseInput(input[i], cb);
+            i++;
+        }
+    }
+    else if (input.type === 'ObjectValue') {
+        const entries = Object.entries(input.value);
+        let i = 0;
+        while (!shouldEarlyExit && i < entries.length) {
+            shouldEarlyExit = traverseInput(entries[i][1], cb, entries[i][0]);
+            i++;
+        }
+    }
+    else if (input.type === 'ArrayValue') {
+        const entries = input.value;
+        let i = 0;
+        while (!shouldEarlyExit && i < entries.length) {
+            shouldEarlyExit = traverseInput(entries[i], cb);
+            i++;
+        }
+    }
+    return shouldEarlyExit;
+}
+exports.traverseInput = traverseInput;
+function traverseParentAdgs(component, doc, cb) {
+    if (component.parentClass &&
+        component.parentClass.type === 'AdgReference' &&
+        doc.adgs?.[component.parentClass.value]) {
+        traverseParentAdgs(doc.adgs?.[component.parentClass.value], doc, cb);
+    }
+    cb(component);
+}
+exports.traverseParentAdgs = traverseParentAdgs;
+/**
+ * Traverse the Komaci Document for a script file and collect property usages.
+ *
+ * This function:
+ * 1. prepares the properties object with initial values
+ * 2. collects usages of properties from wire functions
+ * @param doc Komaci Script Doc to traverse
+ * @returns contextual information about properties
+ */
+function collectPropertyMetadataFromScriptDoc(doc) {
+    if (doc?.exports?.default?.type === 'AdgReference' &&
+        doc?.adgs?.[doc.exports?.default?.value]) {
+        const component = doc.adgs[doc.exports.default.value];
+        let properties = new Map();
+        traverseParentAdgs(component, doc, (currentComponent) => {
+            properties = initializePropertiesMap(currentComponent, doc, properties);
+            for (const functionDetail of currentComponent.functions || []) {
+                if (functionDetail.type === 'WireFunction' && functionDetail.input) {
+                    traverseInput(functionDetail.input, (value) => {
+                        if (value.type === 'PropertyReference' &&
+                            properties.has(value.value)) {
+                            const property = properties.get(value.value);
+                            if (property) {
+                                property.usedInPriming = true;
+                            }
+                        }
+                        return false;
+                    });
+                }
+            }
+        });
+        return properties;
+    }
+    return new Map();
+}
+exports.collectPropertyMetadataFromScriptDoc = collectPropertyMetadataFromScriptDoc;
+/**
+ * Helper to clean up a potential property, see if it exists and update if it does
+ * @param value potential property. could be in the form of record/data/whatever
+ * @param properties map of properties
+ * @param key key to update
+ */
+function updatePropertyIfExists(value, properties, key) {
+    const cleanedUpValue = stripChildReferenceFromValue(value);
+    if (properties.has(cleanedUpValue)) {
+        const property = properties.get(cleanedUpValue);
+        properties.set(cleanedUpValue, {
+            ...property,
+            [key]: true,
+        });
+    }
+}
+/**
+ * Recursively probe a composition and it's children for usages of properties.
+ * @param composition Current composition
+ * @param properties The map of properties to update
+ */
+function updatePropertiesForComposition(composition, properties) {
+    if (composition && composition.key) {
+        const container = composition;
+        if (container.key && container.key.type === 'Binding') {
+            updatePropertyIfExists(container.key.value, properties, 'usedInPriming');
+        }
+    }
+    if (composition && composition.isActive) {
+        updatePropertyIfExists(composition.isActive.input.value, properties, 'usedInPriming');
+    }
+    if (isCompositionAnIteration(composition)) {
+        updatePropertyIfExists(composition.input.value, properties, 'usedInPriming');
+    }
+    if (isCompositionAComposedAdg(composition) && composition.properties) {
+        for (const property of Object.values(composition.properties || {})) {
+            if (property.type === 'Binding') {
+                updatePropertyIfExists(property.value, properties, 'usedInPriming');
+            }
+        }
+        if (composition.input.type === 'Binding') {
+            updatePropertyIfExists(composition.input.value, properties, 'usedInPriming');
+        }
+    }
+    if (isCompositionAnImage(composition)) {
+        // if img.src is a Binding, then let's update the property to note it is used in Priming
+        if (isSrcABinding(composition.src)) {
+            const binding = composition.src;
+            updatePropertyIfExists(binding.value, properties, 'usedInPriming');
+        }
+    }
+    if (composition && composition.compositions) {
+        for (const value of composition.compositions) {
+            updatePropertiesForComposition(value, properties);
+        }
+    }
+}
+exports.updatePropertiesForComposition = updatePropertiesForComposition;
+/**
+ * Collect usages of properties from compositions in a Komaci Template Document
+ * @param doc Komaci Document
+ * @param properties The current map of properties, this is just updating them.
+ */
+function updatePropertyMetadataFromTemplateDoc(doc, properties) {
+    if (doc?.exports?.default?.type === 'CompositionReference' &&
+        doc.compositions?.[doc.exports.default.value]) {
+        const composition = doc.compositions[doc.exports.default.value];
+        updatePropertiesForComposition(composition, properties);
+    }
+}
+exports.updatePropertyMetadataFromTemplateDoc = updatePropertyMetadataFromTemplateDoc;
+/**
+ * Updates used properties to record whether they were used in Priming.
+ * @param prop the name of the getter under consideration
+ * @param identifiers list of member identifiers used in getters
+ * @param properties Map for all class properties and their basic, KomaciDoc analyzable metadata.
+ * @param type The property type so we can make sure the metadata has the right value
+ */
+function updatePropertyUsage(prop, identifiers, properties, type) {
+    const getterProperty = properties.get(prop);
+    if (getterProperty) {
+        getterProperty.type = type;
+    }
+    identifiers.forEach((identifier) => {
+        const property = properties.get(identifier);
+        if (property && getterProperty?.usedInPriming) {
+            property.usedInPriming = true;
+        }
+    });
+}
+exports.updatePropertyUsage = updatePropertyUsage;
+function isPropertyAWire(property) {
+    return property.type === types_1.PropertyTypes.WIRE;
+}
+exports.isPropertyAWire = isPropertyAWire;
+function isPropertyFromImport(property) {
+    return property.imports !== undefined;
+}
+exports.isPropertyFromImport = isPropertyFromImport;
+//# sourceMappingURL=komaciDocumentIntrospection.js.map

package/build/parser.d.ts

@@ -0,0 +1,9 @@
+import { File } from '@babel/types';
+/**
+ * Function that consumes src code from the LWC compiler and returns an AST
+ * Note that there is a possibility of babel throwning an error while parsing src code.
+ * @param srcCode code that will be getting paresd by babel.
+ * @returns an ast representation of the provided srcCode
+ */
+export declare function generateAstFromSrcCode(srcCode: string): File;
+//# sourceMappingURL=parser.d.ts.map

package/build/parser.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAstFromSrcCode = void 0;
+const parser_1 = require("@babel/parser");
+/**
+ * Function that consumes src code from the LWC compiler and returns an AST
+ * Note that there is a possibility of babel throwning an error while parsing src code.
+ * @param srcCode code that will be getting paresd by babel.
+ * @returns an ast representation of the provided srcCode
+ */
+function generateAstFromSrcCode(srcCode) {
+    const ast = (0, parser_1.parse)(srcCode, {
+        sourceType: 'module',
+        plugins: [['decorators', { decoratorsBeforeExport: true }]],
+    });
+    return ast;
+}
+exports.generateAstFromSrcCode = generateAstFromSrcCode;
+//# sourceMappingURL=parser.js.map