@komaci/static-analyzer 240.1.3

package/build/types.d.ts

@@ -0,0 +1,102 @@
+import { Adg, FunctionType, SourceLocation } from '@komaci/types';
+/** Representation of a source code file being analyzed, in format neeed by the VSCode language server */
+export declare type Uri = {
+    path: string;
+    scheme: string;
+    fragment: '';
+    query: '';
+    authority: '';
+};
+/**
+ * When a diagnostic message occurs in a specific file within a bundle, this type contains the information
+ * needed by the VSCode language server, in the format it requires it.
+ */
+export declare type Code = {
+    target: Uri;
+    value: string | number;
+};
+/**
+ * This is consumed by the VSCode language server to enable it to report diagnosics
+ * within the IDE, including the location (Range) of any error, warning, informational occurence.
+ */
+export declare type PrimingDiagnostic = DiagnosticMessage & {
+    range: Range;
+};
+/**
+ * Contains information about a Diagnostic occurence while doing static analysis
+ * in a format compatible with VSCode language server
+ */
+export declare type DiagnosticMessage = {
+    code?: string | number | Code;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    source: 'offline code analyzer';
+};
+export declare type Range = {
+    start: Position;
+    end: Position;
+};
+export declare type Position = {
+    line: number;
+    character: number;
+};
+export declare type AnalyzerInput = DiagnosticFileInfo | DiagnosticBundleInfo;
+export declare type StaticAnalyzerImportInfo = {
+    name: string;
+    namespace: string;
+    location: SourceLocation;
+};
+export declare type WireInfo = {
+    funcIndex: number;
+    propName?: string;
+    isNonAnalyzable: boolean;
+    dependentWires: WireInfo[];
+    location?: SourceLocation;
+    wireFunction: FunctionType;
+    adg: Adg;
+    beingVisited: boolean;
+    visited: boolean;
+};
+export declare type DiagnosticInfo = {
+    type: string;
+    name: string;
+    namespace: string;
+};
+export declare type DiagnosticFileInfo = DiagnosticInfo & {
+    type: 'file';
+    fileName: string;
+    sourceFile: string;
+};
+export declare type DiagnosticBundleInfo = DiagnosticInfo & {
+    type: 'bundle';
+    files: {
+        [fileName: string]: string;
+    };
+};
+export declare type ImportBinding = {
+    importPath: string;
+    identifier: string;
+};
+export declare type PrimingAdapterDefinition = {
+    prime: ImportBinding;
+    batch?: {
+        prime: ImportBinding;
+        reducer: ImportBinding;
+    };
+};
+export declare type GetPrimingAdapter = {
+    (importPath: string, identifier: string): PrimingAdapterDefinition | null;
+};
+export declare type WireAdaptersMapping = {
+    [importPath: string]: {
+        [identifier: string]: PrimingAdapterDefinition;
+    };
+};
+/**
+ * Contextual info about the given contextual code block
+ */
+export declare type FunctionalContext = {
+    declaredVariables: string[];
+    thisAliases: Set<string>;
+};
+//# sourceMappingURL=types.d.ts.map

package/build/types.js

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

package/build/validateGetter.d.ts

@@ -0,0 +1,46 @@
+import * as t from '@babel/types';
+import { NodePath } from '@babel/traverse';
+import { FunctionalContext, PrimingDiagnostic } from './types';
+import { ModuleContext } from '@komaci/common-shared';
+/**
+ * Run a series of checks against a functional node (currently class method or some form of template string) for "purity"
+ *
+ * See the individual invariants for details about each check
+ *
+ * @param path The babel nodepath we are looking at
+ * @param moduleContext Contextual information about the module
+ * @param functionalContext Contextual information about this functional code block
+ * @returns An array of the problems identified
+ */
+export declare function checkFunctionalPurity(path: NodePath<t.ClassMethod | t.ClassProperty>, moduleContext: ModuleContext, functionalContext: FunctionalContext): Array<PrimingDiagnostic>;
+/**
+ * Given a ClassMethod representing a getter method, it will run several invariant checks against its NodePath representation,
+ * in order to determine if it adheres all designated invariants.
+ * @param getterMethodPath NodePath<ClassMethod> path that represents class member-level getter method
+ *                         e.g. "get myId() { return '187291110cd3a'; }"
+ * @param returnSourceLocation if true, we will return an Array<InvariantDetail> for any
+ *                             detected invariants (or empty array if none were found)
+ * @param moduleContext all needful context about items in the class or encapsulating module
+ *
+ * @returns boolean or Array<InvariantDetail> representing whether the validated getter failed one of the
+ *          invariant checks.
+ *
+ *          boolean:
+ *          If returnSourceLocation is false AND none fails the check, true is returned because
+ *          the getter is valid. False is returned otherwise.
+ *          Array<InvariantDetail>:
+ *          Or, if returnSourceLocation is true AND a non-empty Array<InvariantDetail> is returned, that means at
+ *          least one invariant check failed. If no invariant checks failed, an empty Array<InvariantDetail> is returned.
+ */
+export declare function validateGetter(getterMethodPath: NodePath<t.ClassMethod>, moduleContext: ModuleContext, returnSourceLocation?: boolean): boolean | Array<PrimingDiagnostic>;
+/**
+ * Validate template strings for purity. Variable declarations are not valid inside of a template expression so we do not have to support that use case here.
+ * Template string processing is essentially a subset of what we do for getter functions. The only diff is that we don't have to do the extra "only a return statement"
+ * check that we do for getters.
+ * @param node Node Path to check
+ * @param moduleContext contextual details about the module
+ * @param returnSourceLocation if we have to return the priming diagnostics or not
+ * @returns Priming diagnostics or just a true/false if it's valid
+ */
+export declare function validateTemplateString(node: NodePath<t.ClassProperty>, moduleContext: ModuleContext, returnSourceLocation?: boolean): boolean | Array<PrimingDiagnostic>;
+//# sourceMappingURL=validateGetter.d.ts.map

package/build/validateGetter.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTemplateString = exports.validateGetter = exports.checkFunctionalPurity = void 0;
+const memberExpressionInvariantFunctions_1 = require("./invariantFunctions/memberExpressionInvariantFunctions");
+const callExpressionInvariantFunctions_1 = require("./invariantFunctions/callExpressionInvariantFunctions");
+const assignmentExpressionInvariantFunctions_1 = require("./invariantFunctions/assignmentExpressionInvariantFunctions");
+const returnStatementInvariantFunctions_1 = require("./invariantFunctions/returnStatementInvariantFunctions");
+const functionExpressionInvariantFunctions_1 = require("./invariantFunctions/functionExpressionInvariantFunctions");
+const identifierInvariantFunctions_1 = require("./invariantFunctions/identifierInvariantFunctions");
+const common_shared_1 = require("@komaci/common-shared");
+const taggedTemplateExpressionInvariantFunctions_1 = require("./invariantFunctions/taggedTemplateExpressionInvariantFunctions");
+/**
+ * Run a series of checks against a functional node (currently class method or some form of template string) for "purity"
+ *
+ * See the individual invariants for details about each check
+ *
+ * @param path The babel nodepath we are looking at
+ * @param moduleContext Contextual information about the module
+ * @param functionalContext Contextual information about this functional code block
+ * @returns An array of the problems identified
+ */
+function checkFunctionalPurity(path, moduleContext, functionalContext) {
+    let primingDiagnostics = [];
+    const Visitors = {
+        // visitor for each type
+        MemberExpression(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, memberExpressionInvariantFunctions_1.checkNoUsageOfDocumentOrWindow)(path),
+                (0, memberExpressionInvariantFunctions_1.checkForNonSupportedMemberRefs)(path, moduleContext.astContext.classProperties),
+                (0, memberExpressionInvariantFunctions_1.checkForNonExistentMemberRefs)(path, moduleContext.astContext.classProperties, functionalContext.thisAliases),
+                (0, memberExpressionInvariantFunctions_1.checkMemberExpressionForNonSupportedNamespaceRefs)(path, moduleContext.astContext.importDeclarations),
+                (0, memberExpressionInvariantFunctions_1.checkForNoUseOfSuper)(path),
+                (0, memberExpressionInvariantFunctions_1.checkForUnsupportedGlobalRef)(path, moduleContext.astContext, functionalContext.declaredVariables),
+            ]);
+        },
+        CallExpression(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, callExpressionInvariantFunctions_1.checkNoUsageOfEval)(path),
+                (0, callExpressionInvariantFunctions_1.checkCallExpressionForNonSupportedNamespaceRefs)(path, moduleContext.astContext.importDeclarations),
+                (0, callExpressionInvariantFunctions_1.checkForNoReferenceToClassFunctions)(path, moduleContext.astContext.classFunctions),
+                (0, callExpressionInvariantFunctions_1.checkForNoReferenceToModuleFunctions)(path, moduleContext.astContext.moduleFunctions),
+            ]);
+        },
+        AssignmentExpression(path) {
+            const functionCallArr = [(0, assignmentExpressionInvariantFunctions_1.checkForNoMemberVariableAssignments)(path)];
+            if (moduleContext.isExternal) {
+                functionCallArr.push((0, assignmentExpressionInvariantFunctions_1.checkExternalComponentForAssignmentExpr)(path));
+            }
+            primingDiagnostics = processLocationInfo(primingDiagnostics, functionCallArr);
+        },
+        FunctionExpression(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, functionExpressionInvariantFunctions_1.checkForFunctionExpressionIfExternalComponent)(moduleContext, path),
+            ]);
+        },
+        ArrowFunctionExpression(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, functionExpressionInvariantFunctions_1.checkForFunctionExpressionIfExternalComponent)(moduleContext, path),
+            ]);
+        },
+        ObjectMethod(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, functionExpressionInvariantFunctions_1.checkForObjectMethodFunctionDeclarations)(moduleContext, path),
+            ]);
+        },
+        Identifier(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, identifierInvariantFunctions_1.checkForNoReferenceToModuleVariables)(path, moduleContext.astContext.moduleVariables, functionalContext.declaredVariables),
+                (0, identifierInvariantFunctions_1.checkIdentifierForNonSupportedNamespaceRefs)(path, moduleContext.astContext.importDeclarations, functionalContext.declaredVariables),
+            ]);
+        },
+        TaggedTemplateExpression(path) {
+            primingDiagnostics = processLocationInfo(primingDiagnostics, [
+                (0, taggedTemplateExpressionInvariantFunctions_1.checkTaggedTemplateExprForNonSupportedNamespaceRefs)(path, moduleContext.astContext.importDeclarations),
+            ]);
+        },
+    };
+    // traverse the getter method NodePath, checking the logic in the visitors for each corresponding type of node to check
+    path.traverse(Visitors);
+    return primingDiagnostics;
+}
+exports.checkFunctionalPurity = checkFunctionalPurity;
+/**
+ * Given a ClassMethod representing a getter method, it will run several invariant checks against its NodePath representation,
+ * in order to determine if it adheres all designated invariants.
+ * @param getterMethodPath NodePath<ClassMethod> path that represents class member-level getter method
+ *                         e.g. "get myId() { return '187291110cd3a'; }"
+ * @param returnSourceLocation if true, we will return an Array<InvariantDetail> for any
+ *                             detected invariants (or empty array if none were found)
+ * @param moduleContext all needful context about items in the class or encapsulating module
+ *
+ * @returns boolean or Array<InvariantDetail> representing whether the validated getter failed one of the
+ *          invariant checks.
+ *
+ *          boolean:
+ *          If returnSourceLocation is false AND none fails the check, true is returned because
+ *          the getter is valid. False is returned otherwise.
+ *          Array<InvariantDetail>:
+ *          Or, if returnSourceLocation is true AND a non-empty Array<InvariantDetail> is returned, that means at
+ *          least one invariant check failed. If no invariant checks failed, an empty Array<InvariantDetail> is returned.
+ */
+function validateGetter(getterMethodPath, moduleContext, returnSourceLocation = false) {
+    const getterDeclaredVars = (0, common_shared_1.getVariablesDeclaredInGetter)(getterMethodPath);
+    const thisAliases = (0, common_shared_1.getThisAliasDeclaredInGetter)(getterMethodPath);
+    let primingDiagnostics = checkFunctionalPurity(getterMethodPath, moduleContext, {
+        thisAliases,
+        declaredVariables: getterDeclaredVars,
+    });
+    // if getter was defined in an external module
+    if (moduleContext.isExternal) {
+        const blockStatement = getterMethodPath.get('body');
+        const statements = blockStatement.get('body');
+        // the getter doesn't only have a return method as expected. Skip traversal, then return from this method here
+        primingDiagnostics = processLocationInfo(primingDiagnostics, [
+            (0, returnStatementInvariantFunctions_1.checkExternalModuleGetterReturnStatement)(blockStatement, statements),
+        ]);
+        // If checkExternalModuleGetterReturnStatement() fails we should just return. There's no use in
+        // validating a function that is already foundationally invalid
+        if (primingDiagnostics.length > 0) {
+            return returnSourceLocation ? primingDiagnostics : false;
+        }
+    }
+    return returnSourceLocation ? primingDiagnostics : primingDiagnostics.length === 0;
+}
+exports.validateGetter = validateGetter;
+/**
+ * Given a set of results from invariant checks. we want to filter out any no-op values and put meaningful
+ * results into the list of allInvalidLocations
+ * @param allInvalidLocations PrimingDiagnostic[] containing all invariants that occurred so far
+ * @param results the Array<PrimingDiagnostic | undefined> containing what is return by calling invariant checker method.
+ * @returns array of PrimingDiagnostic filtered of no-op values/non-meaningful results.
+ */
+function processLocationInfo(allInvalidLocations, results) {
+    // concat method returns a new array from the original array + the arrays to concatenate
+    return allInvalidLocations.concat(results.filter((result) => result !== undefined));
+}
+/**
+ * Validate template strings for purity. Variable declarations are not valid inside of a template expression so we do not have to support that use case here.
+ * Template string processing is essentially a subset of what we do for getter functions. The only diff is that we don't have to do the extra "only a return statement"
+ * check that we do for getters.
+ * @param node Node Path to check
+ * @param moduleContext contextual details about the module
+ * @param returnSourceLocation if we have to return the priming diagnostics or not
+ * @returns Priming diagnostics or just a true/false if it's valid
+ */
+function validateTemplateString(node, moduleContext, returnSourceLocation = false) {
+    const diagnostics = checkFunctionalPurity(node, moduleContext, {
+        declaredVariables: [],
+        thisAliases: new Set(),
+    });
+    return returnSourceLocation ? diagnostics : diagnostics.length === 0;
+}
+exports.validateTemplateString = validateTemplateString;
+//# sourceMappingURL=validateGetter.js.map

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@komaci/static-analyzer",
+    "version": "240.1.3",
+    "description": "Komaci Diagnostics API",
+    "homepage": "https://komaci.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/komaci.git",
+        "directory": "packages/@komaci/static-analyzer"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/komaci/issues"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "commonjs",
+    "types": "build/index.d.ts",
+    "main": "build/index.js",
+    "scripts": {
+        "build": "tsc -b"
+    },
+    "files": [
+        "build/**/*.js",
+        "build/**/*.d.ts",
+        "build/komaci-mapping.json"
+    ],
+    "peerDependencies": {
+        "@lwc-platform/lwc-metadata-next": "^2.18.0-240.2"
+    },
+    "dependencies": {
+        "@komaci/common-shared": "240.1.3"
+    },
+    "devDependencies": {
+        "@babel/types": "^7.9.0",
+        "@komaci/types": "240.1.3"
+    }
+}