@memberjunction/react-test-harness 2.121.0 → 2.122.0

package/dist/lib/control-flow-analyzer.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Control Flow Analyzer
+ *
+ * Tracks how types and values narrow through JavaScript code based on runtime checks.
+ * Similar to TypeScript's control flow analysis for type narrowing.
+ *
+ * This eliminates false positives in linting rules by understanding patterns like:
+ * - if (x != null) { x.method() }  // x is non-null here
+ * - if (typeof x === 'number') { x + 1 }  // x is number here
+ * - if (arr.length > 0) { arr[0] }  // arr has elements here
+ *
+ * @example
+ * const cfa = new ControlFlowAnalyzer(ast, componentSpec);
+ * if (cfa.isDefinitelyNonNull(node, path)) {
+ *   // Safe to access property - no violation
+ * }
+ */
+import * as t from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import type { ComponentSpec } from '@memberjunction/interactive-component-types';
+export declare class ControlFlowAnalyzer {
+    private ast;
+    private componentSpec?;
+    private typeEngine;
+    constructor(ast: t.File, componentSpec?: ComponentSpec);
+    /**
+     * Check if a node is protected by a ternary/conditional guard
+     * Useful for checking expressions inside template literals within ternaries
+     *
+     * @param node - The node to check (e.g., member expression)
+     * @param path - Current path in the AST (should be close to the node's location)
+     * @returns true if protected by a ternary guard, false otherwise
+     */
+    isProtectedByTernary(node: t.Node, path: NodePath): boolean;
+    /**
+     * Check if a variable/property is definitely non-null at this location
+     *
+     * Detects patterns like:
+     * - if (x != null) { x.method() }  // x is non-null here
+     * - if (x !== undefined) { x.prop }
+     * - if (x) { x.prop }  // truthiness check
+     * - x && x.prop  // short-circuit &&
+     * - x ? x.prop : default  // ternary check
+     *
+     * @param node - The node being accessed (identifier or member expression)
+     * @param path - Current path in the AST
+     * @returns true if guaranteed non-null, false otherwise
+     */
+    isDefinitelyNonNull(node: t.Node, path: NodePath): boolean;
+    /**
+     * Check if a variable is narrowed to a specific type at this location
+     *
+     * Detects patterns like:
+     * - if (typeof x === 'number') { x + 1 }  // x is number
+     * - if (x instanceof Date) { x.getTime() }  // x is Date
+     * - if (Array.isArray(x)) { x.push() }  // x is array
+     *
+     * @param node - The node being checked
+     * @param path - Current path in the AST
+     * @param expectedType - The type to check for ('number', 'string', 'Date', etc.)
+     * @returns true if narrowed to that type, false otherwise
+     */
+    isNarrowedToType(node: t.Node, path: NodePath, expectedType: string): boolean;
+    /**
+     * Recursively check for typeof guards in nested && expressions
+     */
+    private detectTypeofGuardRecursive;
+    /**
+     * Detect typeof guard pattern: typeof x === 'type'
+     */
+    private detectTypeofGuard;
+    /**
+     * Detect null/undefined guard pattern: x != null, x !== null, x !== undefined
+     * Also detects short-circuit OR patterns: !x || x.prop (x.prop is safe due to short-circuit)
+     */
+    private detectNullGuard;
+    /**
+     * Detect truthiness guard pattern: if (x), x && expr, x ? ... : ...
+     *
+     * Handles:
+     * - Simple identifier: if (x)
+     * - Member expression: if (obj.prop)
+     * - Full path matching: if (item.TotalCost) protects item.TotalCost.toFixed()
+     */
+    private detectTruthinessGuard;
+    /**
+     * Check if expression contains a negated check (!x) for the variable
+     * Used for detecting guards within OR chains
+     *
+     * @param expr - Expression to check
+     * @param varName - Variable name to look for
+     * @returns true if !varName exists in the expression
+     */
+    private detectNegatedCheck;
+    /**
+     * Detect negated null guard pattern for alternate branches
+     *
+     * In the alternate (else) branch of these patterns, the variable is proven truthy:
+     * - !x || ... ? ... : <here>  (if !x is false, x is truthy)
+     * - !x.prop || ... ? ... : <here>  (if !x.prop is false, x is truthy)
+     *
+     * @param test - The conditional test expression
+     * @param varName - Variable name or full member path to check
+     * @returns true if the pattern proves varName is truthy in the alternate branch
+     */
+    private detectNegatedNullGuard;
+    /**
+     * Extract variable name or full member expression path from node
+     *
+     * Examples:
+     * - `arr` → "arr"
+     * - `obj.prop` → "obj.prop"
+     * - `result.Results` → "result.Results"
+     * - `accountsResult.Results` → "accountsResult.Results"
+     *
+     * This allows CFA to match guards on nested properties correctly.
+     * For example, guard `accountsResult.Results?.length > 0` protects `accountsResult.Results[0]`
+     */
+    private extractVariableName;
+    /**
+     * Serialize a member expression to its full path string
+     * Handles both regular and optional member expressions
+     *
+     * Examples:
+     * - obj.prop → "obj.prop"
+     * - obj?.prop → "obj.prop" (normalized, ignores optional chaining syntax)
+     * - obj.prop.nested → "obj.prop.nested"
+     */
+    private serializeMemberExpression;
+    /**
+     * Check if path is inside the consequent (then block) of an if/ternary
+     */
+    private isInConsequent;
+    /**
+     * Check if path is in the alternate (else) branch of an if or ternary
+     */
+    private isInAlternate;
+    /**
+     * Check if path is on the right side of a logical && expression
+     */
+    private isInRightSide;
+    /**
+     * Check if an array access is safe due to bounds checking guards
+     *
+     * Detects patterns like:
+     * - if (arr.length > 0) { arr[0] }  // index 0 is safe
+     * - if (arr.length > 2) { arr[2] }  // index 2 is safe
+     * - if (arr.length === 0) return; arr[0]  // early return pattern
+     * - arr.length > 0 && arr[0]  // inline guard
+     * - arr ? arr[0] : default  // ternary guard
+     *
+     * @param arrayNode - The array being accessed (identifier or member expression)
+     * @param accessIndex - The index being accessed (e.g., 0 for arr[0])
+     * @param path - Current path in the AST
+     * @returns true if access is guaranteed safe, false otherwise
+     */
+    isArrayAccessSafe(arrayNode: t.Node, accessIndex: number, path: NodePath): boolean;
+    /**
+     * Extract the maximum safe array index from a length check expression
+     *
+     * Examples:
+     * - arr.length > 0 → returns 0 (index 0 is safe)
+     * - arr?.length > 0 → returns 0 (optional chaining proves non-null)
+     * - arr.length > 2 → returns 2 (indices 0-2 are safe)
+     * - arr.length >= 3 → returns 2 (indices 0-2 are safe)
+     * - arr.length !== 0 → returns 0 (index 0 is safe)
+     *
+     * @param test - The test expression to analyze
+     * @param arrayName - The array variable name to look for
+     * @returns Maximum safe index, or -1 if no length check found
+     */
+    private getMaxSafeIndexFromLengthCheck;
+    /**
+     * Check if an expression is accessing the length property of an array
+     * Handles both regular and optional chaining: arr.length and arr?.length
+     * Also handles nested paths: obj.arr.length and obj.arr?.length
+     */
+    private isLengthAccess;
+    /**
+     * Check if a statement or block contains an early return
+     */
+    private hasEarlyReturn;
+}
+//# sourceMappingURL=control-flow-analyzer.d.ts.map

package/dist/lib/control-flow-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-flow-analyzer.d.ts","sourceRoot":"","sources":["../../src/lib/control-flow-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAClC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAGjF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,UAAU,CAAsB;gBAE5B,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,aAAa;IAMtD;;;;;;;OAOG;IACH,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO;IA0E3D;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO;IA4F1D;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAwD7E;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAelC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;;OAGG;IACH,OAAO,CAAC,eAAe;IA6DvB;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAgC7B;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;IA2BjC;;OAEG;IACH,OAAO,CAAC,cAAc;IA4BtB;;OAEG;IACH,OAAO,CAAC,aAAa;IA4BrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO;IAkHlF;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,8BAA8B;IA8DtC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA2BtB;;OAEG;IACH,OAAO,CAAC,cAAc;CAevB"}