@komaci/common-shared 240.1.3

package/build/utils.js

@@ -0,0 +1,554 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (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.isDeclaredInAst = exports.isExpressionThisOrAlias = exports.getThisAliasDeclaredInGetter = exports.isPropertyNodeUsed = exports.isGetterNodeUsed = exports.isPropertyUsed = exports.getClassMethodName = exports.getVariablesDeclaredInGetter = exports.isExternalModule = exports.getAstContextObject = exports.getAllClassMethods = exports.getAllModuleVaraibles = exports.getAllModuleFunctions = exports.getAllImportReferences = exports.getFromIdentifierOrStringLiteral = exports.collectImportUsage = exports.getMemberVarsFromGetter = exports.implicitConsumptionMetadata = exports.getClassPropertyInfos = exports.getClassProperties = exports.getPropertyMetadataFromAst = exports.ONE_NS = exports.FORCE_NS = exports.LIGHTNING_NS = void 0;
+const t = __importStar(require("@babel/types"));
+const core_1 = require("@babel/core");
+const allowlistNamespaces_1 = require("./allowlistNamespaces");
+exports.LIGHTNING_NS = 'lightning';
+exports.FORCE_NS = 'force';
+exports.ONE_NS = 'one';
+/**
+ * collect node paths for different pieces of a given class so we can more effectively traverse them in the future
+ *
+ * we must do an init traversal to take nodes and turn them into nodepaths, which have context about their position in tree
+ * we need this info so we can do sub tree traversals later.
+ * @param ast babel abstract syntax tree
+ */
+function getPropertyMetadataFromAst(ast) {
+    const nodes = {
+        getters: [],
+        templateStrings: [],
+    };
+    const Visitor = {
+        Program(path) {
+            const exportDefaultDecl = path
+                .get('body')
+                .filter((child) => child.isExportDefaultDeclaration());
+            // "exportDefaultDecl[0]" here is a NodePath<t.ExportDefaultDeclaration>
+            // There can only be one ExportDefaultDeclaration class declaration per file (hence the [0] reference)
+            // ExportDefaultDeclaration can only be at the top level of the file (cannot be in an inner, nested class)
+            if (exportDefaultDecl.length > 0) {
+                const classDecl = exportDefaultDecl[0].get('declaration');
+                if (classDecl.isClassDeclaration()) {
+                    const classBody = classDecl.get('body');
+                    if (classBody.isClassBody()) {
+                        nodes.getters = classBody
+                            .get('body')
+                            .filter((path) => path.node.type === 'ClassMethod' &&
+                            path.node.kind === 'get');
+                        nodes.templateStrings = classBody
+                            .get('body')
+                            .filter((path) => path.node.type === 'ClassProperty' &&
+                            path.node.value &&
+                            (path.node.value.type === 'TemplateLiteral' ||
+                                path.node.value.type ===
+                                    'TaggedTemplateExpression'));
+                    }
+                }
+            }
+        },
+    };
+    (0, core_1.traverse)(ast, Visitor);
+    return nodes;
+}
+exports.getPropertyMetadataFromAst = getPropertyMetadataFromAst;
+/**
+ * @param node
+ * @returns true if node is a ClassBody
+ */
+function isNodeClassBody(node) {
+    return node?.type === 'ClassBody';
+}
+/**
+ * Given the AST of an entire JS source file, this method looks for class member properties.
+ * If there is no default export in the AST, no class properties will be returned (empty array is returned).
+ * @param astRoot AST representing an entire Program, as a @babel/types File object
+ * @returns Array of NodePath<ClassProperty> representing the @babel NodePaths for all class member
+ *          properties, if any exist. Otherwise, returns an empty array.
+ */
+function getClassProperties(astRoot) {
+    let classProperties = [];
+    const prog = astRoot.program;
+    const body = prog.body;
+    const exportDefaultDecl = body.filter((child) => child.type === 'ExportDefaultDeclaration');
+    if (exportDefaultDecl.length > 0) {
+        const classDecl = exportDefaultDecl[0]
+            .declaration; // there can only be one export default declaration
+        if (isNodeClassBody(classDecl.body)) {
+            const classBody = classDecl.body;
+            classProperties = classBody.body.filter((classChild) => classChild.type === 'ClassProperty' ||
+                (classChild.type === 'ClassMethod' && classChild.kind === 'get'));
+        }
+    }
+    return classProperties;
+}
+exports.getClassProperties = getClassProperties;
+/**
+ * Utility method that takes in an @babel/types ClassProperty array, and returns an array of ClassPropertyInfo
+ * objects containing information about each ClassProperty from the input array.
+ * @param classProperties
+ * @returns Array of ClassPropertyInfo, where each element corresponds to the input ClassProperty array.
+ */
+function getClassPropertyInfos(classProperties = []) {
+    const classPropInfos = [];
+    classProperties
+        .filter((classProp) => t.isIdentifier(classProp.key))
+        .forEach((classProp) => {
+        const id = classProp.key;
+        const decorators = classProp.decorators;
+        let decoratorType = undefined;
+        if (decorators) {
+            // non-annotated class properties won't have a decorator
+            const expr = decorators[0].expression;
+            if (expr.type === 'CallExpression') {
+                const callee = expr.callee;
+                decoratorType = callee.name;
+            }
+            else if (expr.type === 'Identifier') {
+                decoratorType = expr.name;
+            }
+        }
+        const classPropInfo = {
+            classProp: classProp,
+            classPropId: id.name,
+            isDecorated: decorators !== undefined &&
+                decorators !== null &&
+                decorators.length > 0,
+            hasInitialValue: t.isClassProperty(classProp)
+                ? classProp.value !== null
+                : false,
+        };
+        if (classPropInfo.isDecorated) {
+            classPropInfo.decoratorType = decoratorType;
+        }
+        classPropInfos.push(classPropInfo);
+    });
+    return classPropInfos;
+}
+exports.getClassPropertyInfos = getClassPropertyInfos;
+/**
+ * Given a valid functional node (tempalte string or getter function), collect information that we may not have been able to collect via KomaciDocument
+ * and return a list of class member variables that are properly used in the method body.
+ * "properly" = i.e. used in the right-hand side of a member expression.
+ * @param getter NodePath<ClassMethod | Class Property> path that represents class member-level getter method or template string
+ *               e.g. "get myId() { return '187291110cd3a'; }"
+ * @param classPropInfos ClassPropertyInfo[] that contains all of the class-level properties.
+ * @param importDeclarations Map<string, ImporDeclarationInfo> which contains metadata for all import statements
+ *                           that currently exist. Does not contain state as to whether that import is being used.
+ * @param moduleLevelConsumption ModuleLevelConsumption. Contains a ConsumedImports which in turn contains a Map<string, ImportDetail>
+ *                               which in turn holds state as tp which imports are currently being used
+ * @returns ImplicitConsumption, which contains an array representing the properly-used member variables.
+ *          Returns ImplicitConsumption with an empty array if none were found.
+ */
+function implicitConsumptionMetadata(node, classPropInfos, importDeclarations, // import metadata
+moduleLevelConsumption) {
+    const identifiers = new Set();
+    const Visitors = {
+        // visitor for each type
+        MemberExpression(path) {
+            getMemberVarsFromGetter(path, identifiers);
+        },
+        Identifier(path) {
+            collectImportUsage(path, classPropInfos, importDeclarations, moduleLevelConsumption.consumedImports);
+        },
+    };
+    node.traverse(Visitors);
+    return { identifiers: Array.from(identifiers) };
+}
+exports.implicitConsumptionMetadata = implicitConsumptionMetadata;
+/*
+ * Given a valid getter method (class method), return a list of class member variables that are properly
+ * used in the method body. "properly" = i.e. used in the right-hand side of a member expression.
+ * @param getterMethodPath NodePath<ClassMethod> path that represents class member-level getter method
+ *                         e.g. "get myId() { return '187291110cd3a'; }"
+ * @param Set<string> representing the properly-used member variables. We add names to this as they are d
+ *                    eemed to be member vars
+ */
+function getMemberVarsFromGetter(path, identifiers) {
+    if (path.get('object').type === 'ThisExpression' &&
+        path.get('property').type === 'Identifier') {
+        const identifier = path.get('property').node;
+        if (!identifiers.has(identifier.name)) {
+            identifiers.add(identifier.name);
+        }
+    }
+}
+exports.getMemberVarsFromGetter = getMemberVarsFromGetter;
+/**
+ * Collect metadata about all the imports consumed for an identifier in a getter
+ * @param path NodePath of the current Identifier in the getter
+ * @param classPropInfos Array of ClassPropertyInfo objects that have all of the information
+ *        related to all class properties in the class.
+ * @param importDeclarations Metadata about all the imports
+ * @param consumedImports The map to add info to about this identifier, whether it is an import that is being used
+ *                        in the getter, or if it is assigned an import being used in the getter.
+ */
+function collectImportUsage(path, classPropInfos, importDeclarations, consumedImports) {
+    const name = path.node.name;
+    let nameToReference = name;
+    let importInfo = importDeclarations.get(name); // finds direct references of import specifiers in the getter
+    // i.e. find `MyID1.CONST` in the getter, where `MyID1` is an import specifier
+    if (!importInfo &&
+        path.parent.type === 'MemberExpression' &&
+        path.parent.object.type === 'Identifier' &&
+        path.parent.object === path.node) {
+        importInfo = importDeclarations.get(path.parent.object.name);
+    }
+    // find indirect import references (where import was assigned to a class member variable)
+    if (!importInfo) {
+        const importSpecifierNames = new Set(Array.from(importDeclarations.keys()));
+        classPropInfos.forEach((classPropInfo) => {
+            // check for type NodePath<t.ClassProperty> vs. t.ClassProperty. The former has a .node property
+            const isNodePath = classPropInfo.classProp.node !== undefined;
+            const classProp = isNodePath
+                ? classPropInfo.classProp.node
+                : classPropInfo.classProp;
+            if (classProp.key.type === 'Identifier' &&
+                classProp.key.name === name &&
+                classProp.value?.type === 'Identifier' &&
+                importSpecifierNames.has(classProp.value.name)) {
+                importInfo = importDeclarations.get(classProp.value.name);
+            }
+        });
+    }
+    if (importInfo) {
+        if (importInfo.isDefault) {
+            nameToReference = 'default';
+        }
+        else if (importInfo.isNamespaceSpecifier) {
+            // this case needs to be handled separately as it always has an alias
+            nameToReference = '*';
+        }
+        else if (importInfo.trueName) {
+            nameToReference = importInfo.trueName;
+        }
+        let fullImportContext = consumedImports.get(importInfo.namespace);
+        if (fullImportContext && !fullImportContext.names.has(name)) {
+            fullImportContext.names.add(nameToReference);
+        }
+        else if (!fullImportContext) {
+            const names = new Set();
+            names.add(nameToReference);
+            fullImportContext = {
+                names,
+                resourceName: importInfo.namespace,
+                isNamespaceSpecifier: importInfo.isNamespaceSpecifier,
+                isDefaultSpecifier: importInfo.isDefault,
+                isSupported: importInfo.isSupported,
+            };
+        }
+        consumedImports.set(importInfo.namespace, fullImportContext);
+    }
+}
+exports.collectImportUsage = collectImportUsage;
+/**
+ * Some children of nodes can be a direct identifier or a string literal. helper helps do
+ * this consistant dance of getting the value from either
+ * @param node Node to ge value of
+ * @returns value
+ */
+function getFromIdentifierOrStringLiteral(node) {
+    return node.type === 'Identifier' ? node.name : node.value;
+}
+exports.getFromIdentifierOrStringLiteral = getFromIdentifierOrStringLiteral;
+/**
+ * Function for getting an array of supported namesapce references.
+ * @param astRoot the root of the ast
+ * @returns an Array of supported namespace references.
+ */
+function getAllImportReferences(astRoot) {
+    const importReferences = new Map();
+    const program = astRoot.program;
+    const body = program.body;
+    const importDeclarations = body.filter((currentDec) => currentDec.type === 'ImportDeclaration');
+    importDeclarations.forEach((currentDec) => {
+        const isValid = isValidNamespace(currentDec.source.value) &&
+            (0, allowlistNamespaces_1.isLibraryValid)(currentDec.source.value);
+        const specifiers = currentDec.specifiers;
+        specifiers.forEach((currentSpecifier) => {
+            let importName = undefined;
+            if (currentSpecifier.type === 'ImportSpecifier') {
+                importName = currentSpecifier.local // local is alias (the most specific name)
+                    ? getFromIdentifierOrStringLiteral(currentSpecifier.local)
+                    : getFromIdentifierOrStringLiteral(currentSpecifier.imported);
+            }
+            else {
+                importName = getFromIdentifierOrStringLiteral(currentSpecifier.local);
+            }
+            importReferences.set(importName, {
+                namespace: currentDec.source.value,
+                identifierName: importName,
+                isSupported: isValid,
+                isDefault: currentSpecifier.type === 'ImportDefaultSpecifier',
+                isNamespaceSpecifier: currentSpecifier.type === 'ImportNamespaceSpecifier',
+                trueName: currentSpecifier.type === 'ImportSpecifier'
+                    ? getFromIdentifierOrStringLiteral(currentSpecifier.imported)
+                    : undefined,
+            });
+        });
+    });
+    return importReferences;
+}
+exports.getAllImportReferences = getAllImportReferences;
+/**
+ * Helper function to validate if a namespace is in our allowed namespace list.
+ * @param namespace the namespace to validate.
+ * @returns true of the namespace is supported, false if unsupported.
+ */
+function isValidNamespace(importPath) {
+    return (0, allowlistNamespaces_1.isNamespaceInternal)((0, allowlistNamespaces_1.getNamespaceFromImport)(importPath));
+}
+/**
+ * Function to get an array of function names that are defined at the module level.
+ * @returns an array of function names that are defined at the module level.
+ */
+function getAllModuleFunctions(astRoot) {
+    const result = [];
+    const program = astRoot.program;
+    const body = program.body;
+    const declarations = body.filter((currentDec) => currentDec.type === 'FunctionDeclaration' ||
+        currentDec.type === 'VariableDeclaration');
+    declarations.forEach((currentDec) => {
+        if (currentDec.type === 'FunctionDeclaration') {
+            const functionDec = currentDec;
+            if (functionDec.id) {
+                result.push(functionDec.id.name);
+            }
+        }
+        if (currentDec.type === 'VariableDeclaration') {
+            const varDeclarator = currentDec.declarations[0];
+            if (varDeclarator.init?.type === 'ArrowFunctionExpression' ||
+                varDeclarator.init?.type === 'FunctionExpression') {
+                if (varDeclarator.id.type === 'Identifier') {
+                    result.push(varDeclarator.id.name);
+                }
+                if (varDeclarator.id.type === 'ObjectPattern') {
+                    varDeclarator.id.properties.forEach((currentProp) => {
+                        result.push(currentProp.value.name);
+                    });
+                }
+            }
+        }
+    });
+    return result;
+}
+exports.getAllModuleFunctions = getAllModuleFunctions;
+/**
+ * Function that returns an array of variable names that are defined at the module level.
+ * @param astRoot the root ast node.
+ * @returns an array of variable names that are defined at the module level.
+ */
+function getAllModuleVaraibles(astRoot) {
+    const result = [];
+    const program = astRoot.program;
+    const body = program.body;
+    const varDeclarations = body.filter((currentDec) => currentDec.type === 'VariableDeclaration');
+    varDeclarations.forEach((currentDec) => {
+        const declarator = currentDec.declarations[0];
+        if (declarator.init?.type != 'FunctionExpression' &&
+            declarator.init?.type != 'ArrowFunctionExpression') {
+            if (declarator.id.type === 'Identifier') {
+                result.push(declarator.id.name);
+            }
+            if (declarator.id.type === 'ObjectPattern') {
+                declarator.id.properties.forEach((currentProp) => {
+                    result.push(currentProp.value.name);
+                });
+            }
+        }
+    });
+    return result;
+}
+exports.getAllModuleVaraibles = getAllModuleVaraibles;
+/**
+ * Function to get an array of function names that are defined on the default exports class.
+ * @returns an array of function names that are defined on the class.
+ */
+function getAllClassMethods(astRoot) {
+    const result = [];
+    const program = astRoot.program;
+    const body = program.body;
+    const exportDefaultDec = body.filter((currentDec) => currentDec.type === 'ExportDefaultDeclaration');
+    const classBodyArr = exportDefaultDec[0]?.declaration.body
+        ?.body;
+    if (classBodyArr) {
+        classBodyArr.forEach((dec) => {
+            if (dec.type === 'ClassMethod') {
+                const identifier = dec.key;
+                result.push(identifier.name);
+            }
+            if (dec.type === 'ClassProperty') {
+                const classProperty = dec;
+                if (classProperty.value?.type === 'FunctionExpression' ||
+                    classProperty.value?.type === 'ArrowFunctionExpression') {
+                    result.push(classProperty.key.name);
+                }
+            }
+        });
+    }
+    return result;
+}
+exports.getAllClassMethods = getAllClassMethods;
+/**
+ * Function to get an AstContext object for a given ast.
+ * @param ast the ast.
+ * @returns a context object containing meta data about the ast.
+ */
+function getAstContextObject(ast) {
+    const props = getClassProperties(ast);
+    const context = {
+        importDeclarations: getAllImportReferences(ast),
+        moduleFunctions: getAllModuleFunctions(ast),
+        moduleVariables: getAllModuleVaraibles(ast),
+        classProperties: getClassPropertyInfos(props),
+        classFunctions: getAllClassMethods(ast),
+    };
+    return context;
+}
+exports.getAstContextObject = getAstContextObject;
+/** Determines if the module (i.e LWC Component) was written by an external user. If the namespace of the module
+ * exactly matches one of 'lightning', 'force', or 'one', it is NOT an external component.
+ * @param namespace string namespace of the ModuleInfo to check (comes from ModuleInfo.namespace)
+ * @returns true if moduleInfo is an external module, false otherwise
+ */
+function isExternalModule(namespace) {
+    return !(namespace === exports.LIGHTNING_NS ||
+        namespace === exports.FORCE_NS ||
+        namespace === exports.ONE_NS);
+}
+exports.isExternalModule = isExternalModule;
+/**
+ * Helper function to collect all variables declared within a getter method.
+ * @param getterMethodPath the babel path object of the getter method.
+ * @returns an array of variable names that were declared in the getter method.
+ */
+function getVariablesDeclaredInGetter(getterMethodPath) {
+    const variables = [];
+    const getterMethodNode = getterMethodPath.node;
+    const declarations = getterMethodNode.body.body.filter((dec) => dec.type === 'VariableDeclaration');
+    declarations.forEach((dec) => {
+        dec.declarations.forEach((declarator) => {
+            variables.push(declarator.id.name);
+        });
+    });
+    return variables;
+}
+exports.getVariablesDeclaredInGetter = getVariablesDeclaredInGetter;
+/**
+ * Helper to get the name of a method
+ * @param node The method node
+ * @returns the name of the node
+ */
+function getClassMethodName(node) {
+    return getFromIdentifierOrStringLiteral(node.node.key);
+}
+exports.getClassMethodName = getClassMethodName;
+/**
+ * Check whether a property is used either directly or indirectly
+ * @param prop The prop details
+ * @returns if it is used
+ */
+function isPropertyUsed(prop) {
+    return prop?.usedInPriming || false;
+}
+exports.isPropertyUsed = isPropertyUsed;
+/**
+ * High level wrapper to parse getter info from a babel node before checking if it is used
+ * @param getter The getter node
+ * @param properties Metadata about class properties
+ * @returns if it is used directly
+ */
+function isGetterNodeUsed(getter, properties) {
+    const getterName = getClassMethodName(getter);
+    const getterMeta = properties.get(getterName);
+    return isPropertyUsed(getterMeta);
+}
+exports.isGetterNodeUsed = isGetterNodeUsed;
+/**
+ * High level wrapper to parse prop info from a babel node before checking if it is used
+ * @param prop The prop babel node
+ * @param properties Metadata about class properties
+ * @returns if it is used directly
+ */
+function isPropertyNodeUsed(prop, properties) {
+    if (prop.node.key.type === 'Identifier' || prop.node.key.type === 'StringLiteral') {
+        const propName = getFromIdentifierOrStringLiteral(prop.node.key);
+        const meta = properties.get(propName);
+        return isPropertyUsed(meta);
+    }
+    else {
+        // expression props are not things we can process
+        return false;
+    }
+}
+exports.isPropertyNodeUsed = isPropertyNodeUsed;
+/**
+ * @author xiaoxugu
+ * Helper function to collect all variables declared as alias of this.
+ * eg. const self = this, const that = this.
+ * @param getterMethodPath the babel path object of the getter method.
+ * @returns a {Set<string>} of variable names that were declared as alias of 'this'.
+ */
+function getThisAliasDeclaredInGetter(getterMethodPath) {
+    const variables = new Set();
+    const getterMethodNode = getterMethodPath.node;
+    const declarations = getterMethodNode.body.body.filter((dec) => dec.type === 'VariableDeclaration');
+    declarations.forEach((dec) => {
+        dec.declarations.forEach((declarator) => {
+            if (isExpressionThisOrAlias(variables, declarator.init)) {
+                variables.add(declarator.id.name);
+            }
+        });
+    });
+    return variables;
+}
+exports.getThisAliasDeclaredInGetter = getThisAliasDeclaredInGetter;
+/**
+ * @author xiaoxugu
+ * Determines whether the passed in {Expression} is a `this` or whether it is an equivalent alias to `this`
+ * @param {Set<string>} aliases a Set<string> of variables that were assigned `this`
+ * @param {Expression | null | undefined} expr the Expression whose type is being evaluated
+ * @returns {boolean} returns true is the Expression is a `ThisExpression` or an alias to one
+ */
+function isExpressionThisOrAlias(aliases, expr) {
+    if (expr) {
+        return (expr.type === 'ThisExpression' ||
+            (expr.type === 'Identifier' && aliases.has(expr.name)));
+    }
+    return false;
+}
+exports.isExpressionThisOrAlias = isExpressionThisOrAlias;
+/**
+ * Function to check if the id we are referecing is either declared as a class property, import reference or module variale
+ * @param astContext the ast context
+ * @param declaredGetterVars a collection of variables declared within the getter
+ * @param id the id of the member we are referencing.
+ */
+function isDeclaredInAst(astContext, declaredGetterVars, id) {
+    const { classProperties, importDeclarations, moduleVariables } = astContext;
+    return (classProperties.find((prop) => prop.classPropId === id) !== undefined ||
+        importDeclarations.has(id) ||
+        moduleVariables.find((varId) => varId === id) !== undefined ||
+        (declaredGetterVars || []).find((varId) => varId === id) !== undefined);
+}
+exports.isDeclaredInAst = isDeclaredInAst;
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@komaci/common-shared",
+    "version": "240.1.3",
+    "description": "Assets that are shared across Komaci commonjs packages",
+    "homepage": "https://komaci.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/komaci.git",
+        "directory": "packages/@komaci/common-shared"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/komaci/issues"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "commonjs",
+    "types": "build/index.d.ts",
+    "main": "build/index.js",
+    "module": "build/index.js",
+    "scripts": {
+        "build": "tsc -b"
+    },
+    "files": [
+        "build/**/*.js",
+        "build/**/*.d.ts",
+        "build/internal-namespaces.json"
+    ],
+    "devDependencies": {
+        "@komaci/types": "240.1.3"
+    },
+    "dependencies": {
+        "@babel/core": "^7.9.0",
+        "@babel/generator": "^7.9.0"
+    }
+}