@nitronjs/framework 0.2.26 → 0.3.0

package/lib/Build/PropUsageAnalyzer.js

@@ -0,0 +1,1189 @@
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import fs from "fs";
+import { mergeUsageTrees } from "./propUtils.js";
+
+const _traverse = traverse.default;
+const ARRAY_METHODS = new Set(["map", "forEach", "filter", "find", "some", "every", "reduce", "flatMap", "findIndex"]);
+
+/**
+ * Analyzes "use client" components at build time to extract prop usage trees.
+ * Determines which props (and sub-properties) a client component actually accesses,
+ * enabling the runtime to strip unused data from the Flight payload.
+ *
+ * Returns:
+ *   - An object (usage tree) if prop usage is detectable
+ *   - null if all props should pass through (spread, dynamic access, parse failure)
+ *
+ * @example
+ * // Component: function Card({ item }) { return <div>{item.title}</div> }
+ * // Result:    { item: { title: true } }
+ */
+class PropUsageAnalyzer {
+    /**
+     * Analyze a client component file and extract its prop usage tree.
+     * @param {string} filePath - Absolute path to the .tsx file.
+     * @returns {object|null} Usage tree or null (passthrough).
+     */
+    static analyze(filePath) {
+        const parsed = parseFile(filePath);
+        if (!parsed) return null;
+
+        const funcPaths = findComponentFunction(parsed.ast);
+        if (!funcPaths) return null;
+
+        // Analyze all exported components and merge their usage trees.
+        // This way all named exports' props are included in the filter.
+        let merged = null;
+
+        for (const funcPath of funcPaths) {
+            const usage = extractPropUsage(funcPath);
+
+            if (usage === null) return null;
+            if (!merged) { merged = usage; }
+            else if (usage) { merged = mergeUsageTrees(merged, usage); }
+        }
+
+        // Meta export can also access props (e.g. Meta = ({ admin }) => ({ title: admin.username }))
+        // Merge Meta's usage so safeParams includes fields needed by both component and Meta.
+        const metaFuncPath = findMetaFunction(parsed.ast);
+
+        if (!metaFuncPath) return merged;
+
+        const metaUsage = extractPropUsage(metaFuncPath);
+
+        if (!metaUsage) return merged;
+        if (!merged) return metaUsage;
+
+        return mergeUsageTrees(merged, metaUsage);
+    }
+
+    /**
+     * Analyze JSX prop forwarding patterns in a client component.
+     * Detects when a component passes its props directly to child components.
+     *
+     * @example
+     * // function Wrapper({ data }) {
+     * //     return <Display info={data} />;
+     * // }
+     * // Result: { forwards: [{ parentProp: "data", childImport: "./Display", childProp: "info" }] }
+     *
+     * @param {string} filePath - Absolute path to the .tsx file.
+     * @returns {{forwards: Array, imports: object}|null}
+     */
+    static analyzeForwarding(filePath) {
+        const parsed = parseFile(filePath);
+        if (!parsed) return null;
+
+        const imports = extractImports(parsed.ast);
+        const funcPaths = findComponentFunction(parsed.ast);
+        if (!funcPaths) return null;
+
+        // Use the primary component (default export, or first named) for forwarding analysis
+        return extractForwards(funcPaths[0], imports);
+    }
+
+    /**
+     * Analyze a file and extract prop usage, forwarding, and translation keys
+     * from a single parse pass. Use this instead of calling analyze() + analyzeForwarding()
+     * separately to avoid double file I/O and double Babel parse.
+     *
+     * @param {string} filePath - Absolute path to the .tsx/.jsx file.
+     * @returns {{propUsage: object|null, forwarding: {forwards: Array, imports: object}|null, hasDefaultExport: boolean, translationKeys: string[]|null}}
+     */
+    static analyzeAll(filePath) {
+        const parsed = parseFile(filePath);
+        if (!parsed) return { propUsage: null, forwarding: null, hasDefaultExport: false, translationKeys: null };
+
+        // Extract translation keys BEFORE findComponentFunction (server files may not have components)
+        const translationKeys = extractTranslationKeys(parsed.ast);
+
+        const hasDefaultExport = hasDefault(parsed.ast);
+
+        const funcPaths = findComponentFunction(parsed.ast);
+        if (!funcPaths) return { propUsage: null, forwarding: null, hasDefaultExport, translationKeys };
+
+        // Merge all exported components' usage trees into one
+        let propUsage = null;
+
+        for (const funcPath of funcPaths) {
+            const usage = extractPropUsage(funcPath);
+
+            if (usage === null) { propUsage = null; break; }
+            if (!propUsage) { propUsage = usage; }
+            else if (usage) { propUsage = mergeUsageTrees(propUsage, usage); }
+        }
+
+        // Also merge Meta export usage
+        const metaFuncPath = findMetaFunction(parsed.ast);
+
+        if (metaFuncPath) {
+            const metaUsage = extractPropUsage(metaFuncPath);
+
+            if (metaUsage) {
+                propUsage = propUsage ? mergeUsageTrees(propUsage, metaUsage) : metaUsage;
+            }
+        }
+
+        const imports = extractImports(parsed.ast);
+        const forwarding = extractForwards(funcPaths[0], imports);
+
+        return { propUsage, forwarding, hasDefaultExport, translationKeys };
+    }
+}
+
+
+/**
+ * Parses a file and returns source + AST. Shared by analyze() and analyzeForwarding().
+ * @param {string} filePath
+ * @returns {{source: string, ast: object}|null}
+ */
+function parseFile(filePath) {
+    let source;
+
+    try {
+        source = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+
+    let ast;
+
+    try {
+        ast = parse(source, {
+            sourceType: "module",
+            plugins: ["typescript", "jsx"]
+        });
+    }
+    catch {
+        return null;
+    }
+
+    return { source, ast };
+}
+
+/**
+ * Extracts all imports from an AST as { localName → importSource }.
+ * @param {object} ast
+ * @returns {object}
+ */
+function extractImports(ast) {
+    const imports = {};
+
+    _traverse(ast, {
+        ImportDeclaration(p) {
+            const src = p.node.source.value;
+
+            for (const spec of p.node.specifiers) {
+                imports[spec.local.name] = src;
+            }
+        }
+    });
+
+    return imports;
+}
+
+/**
+ * Extracts JSX prop forwarding patterns from a component function.
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @param {object} imports - Import map { localName → importSource }.
+ * @returns {{forwards: Array, imports: object}}
+ */
+function extractForwards(funcPath, imports) {
+    const propVarMap = extractPropVarMap(funcPath);
+    const propsIdentifier = extractPropsIdentifier(funcPath);
+
+    if (!propVarMap && !propsIdentifier) return { forwards: [], imports };
+
+    const forwards = [];
+
+    funcPath.traverse({
+        JSXOpeningElement(jsxPath) {
+            const tag = jsxPath.node.name;
+            if (tag.type !== "JSXIdentifier") return;
+
+            const tagName = tag.name;
+            if (!tagName || tagName[0] !== tagName[0].toUpperCase()) return;
+            if (!imports[tagName]) return;
+
+            for (const attr of jsxPath.node.attributes) {
+                if (attr.type !== "JSXAttribute") continue;
+
+                const childProp = attr.name?.name;
+                if (!childProp) continue;
+
+                const value = attr.value;
+                if (!value || value.type !== "JSXExpressionContainer") continue;
+
+                const expr = value.expression;
+
+                // Pattern 1: { data } destructured → <Child info={data} />
+                if (propVarMap && expr.type === "Identifier" && propVarMap.has(expr.name)) {
+                    forwards.push({
+                        parentProp: propVarMap.get(expr.name),
+                        childImport: imports[tagName],
+                        childProp,
+                        childTag: tagName
+                    });
+                }
+
+                // Pattern 2: (props) identifier → <Child info={props.data} />
+                if (propsIdentifier &&
+                    expr.type === "MemberExpression" &&
+                    expr.object.type === "Identifier" &&
+                    expr.object.name === propsIdentifier &&
+                    !expr.computed &&
+                    expr.property.type === "Identifier") {
+                    forwards.push({
+                        parentProp: expr.property.name,
+                        childImport: imports[tagName],
+                        childProp,
+                        childTag: tagName
+                    });
+                }
+            }
+        }
+    });
+
+    return { forwards, imports };
+}
+
+/**
+ * Extracts a Map of variable names → original prop keys from destructured params.
+ * { admin: myAdmin } → Map { "myAdmin" → "admin" }
+ * { admin } → Map { "admin" → "admin" }
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @returns {Map<string, string>|null}
+ */
+function extractPropVarMap(funcPath) {
+    const params = funcPath.node.params;
+    if (!params || params.length === 0) return null;
+
+    let pattern = params[0];
+
+    if (pattern.type === "AssignmentPattern") pattern = pattern.left;
+    if (pattern.type !== "ObjectPattern") return null;
+
+    const map = new Map();
+
+    for (const prop of pattern.properties) {
+        if (prop.type === "RestElement") return null;
+
+        const key = prop.key?.name || prop.key?.value;
+        if (!key) continue;
+
+        const value = prop.value;
+
+        if (value && value.type === "Identifier") {
+            map.set(value.name, key);
+        }
+        else if (value && value.type === "AssignmentPattern" && value.left?.type === "Identifier") {
+            map.set(value.left.name, key);
+        }
+        else {
+            map.set(key, key);
+        }
+    }
+
+    return map.size > 0 ? map : null;
+}
+
+/**
+ * Extracts the props identifier name when using (props) => ... pattern.
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @returns {string|null}
+ */
+function extractPropsIdentifier(funcPath) {
+    const params = funcPath.node.params;
+    if (!params || params.length === 0) return null;
+
+    let param = params[0];
+
+    if (param.type === "AssignmentPattern") param = param.left;
+    if (param.type === "Identifier") return param.name;
+
+    return null;
+}
+
+/**
+ * Finds all exported component functions in the AST.
+ * Returns the default export (priority) plus any named export components.
+ * Meta and Layout named exports are excluded (not components).
+ * @param {object} ast - Babel AST.
+ * @returns {import("@babel/traverse").NodePath|null} Single function path, or null.
+ */
+function findComponentFunction(ast) {
+    let defaultExport = null;
+    const namedExports = [];
+    const SKIP_NAMES = new Set(["Meta", "Layout"]);
+
+    _traverse(ast, {
+        ExportDefaultDeclaration(path) {
+            const decl = path.node.declaration;
+
+            // export default function Comp() {}
+            if (decl.type === "FunctionDeclaration") {
+                defaultExport = path.get("declaration");
+                return;
+            }
+
+            // export default () => {}
+            if (decl.type === "ArrowFunctionExpression" || decl.type === "FunctionExpression") {
+                defaultExport = path.get("declaration");
+                return;
+            }
+
+            // export default memo(() => {}) or forwardRef(() => {})
+            if (decl.type === "CallExpression") {
+                const unwrapped = unwrapHOC(decl, path.get("declaration"));
+
+                if (unwrapped) {
+                    defaultExport = unwrapped;
+                    return;
+                }
+            }
+
+            // export default Comp (reference to a variable or function)
+            if (decl.type === "Identifier") {
+                const binding = path.scope.getBinding(decl.name);
+                if (!binding) return;
+
+                const bp = binding.path;
+
+                // function Comp() {}
+                if (bp.isFunctionDeclaration()) {
+                    defaultExport = bp;
+                    return;
+                }
+
+                // const Comp = () => {} or const Comp = memo(() => {})
+                if (bp.isVariableDeclarator()) {
+                    const init = bp.node.init;
+                    if (!init) return;
+
+                    if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+                        defaultExport = bp.get("init");
+                        return;
+                    }
+
+                    const unwrapped = unwrapHOC(init, bp.get("init"));
+
+                    if (unwrapped) {
+                        defaultExport = unwrapped;
+                    }
+                }
+            }
+        },
+
+        ExportNamedDeclaration(path) {
+            const decl = path.node.declaration;
+            if (!decl) return;
+
+            // export function Button({ label }) {}
+            if (decl.type === "FunctionDeclaration" && decl.id?.name && !SKIP_NAMES.has(decl.id.name)) {
+                namedExports.push(path.get("declaration"));
+                return;
+            }
+
+            // export const Button = () => {} or export const Button = memo(...)
+            if (decl.type === "VariableDeclaration") {
+                for (let i = 0; i < decl.declarations.length; i++) {
+                    const declarator = decl.declarations[i];
+                    const init = declarator.init;
+
+                    if (!init || SKIP_NAMES.has(declarator.id?.name)) continue;
+
+                    if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+                        namedExports.push(path.get(`declaration.declarations.${i}.init`));
+                    }
+                    else if (init.type === "CallExpression") {
+                        const unwrapped = unwrapHOC(init, path.get(`declaration.declarations.${i}.init`));
+
+                        if (unwrapped) {
+                            namedExports.push(unwrapped);
+                        }
+                    }
+                }
+            }
+        }
+    });
+
+    // Return all found component functions for merged analysis.
+    const all = [];
+    if (defaultExport) all.push(defaultExport);
+    all.push(...namedExports);
+
+    return all.length > 0 ? all : null;
+}
+
+/**
+ * Finds the exported Meta function in the AST.
+ * Meta can be a function that receives props and returns meta tags:
+ *   export const Meta = (props) => ({ title: props.pageData.title })
+ *   export const Meta = ({ admin }) => ({ title: admin.username })
+ * Static Meta objects (export const Meta = { title: "Dashboard" }) are skipped
+ * because they don't access props.
+ * @param {object} ast - Babel AST.
+ * @returns {import("@babel/traverse").NodePath|null}
+ */
+function findMetaFunction(ast) {
+    let result = null;
+
+    _traverse(ast, {
+        ExportNamedDeclaration(path) {
+            const decl = path.node.declaration;
+            if (!decl || decl.type !== "VariableDeclaration") return;
+
+            for (let i = 0; i < decl.declarations.length; i++) {
+                const declarator = decl.declarations[i];
+
+                if (declarator.id?.name !== "Meta") continue;
+
+                const init = declarator.init;
+                if (!init) continue;
+
+                if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+                    result = path.get(`declaration.declarations.${i}.init`);
+                }
+            }
+        }
+    });
+
+    return result;
+}
+
+/**
+ * Checks if the AST has an ExportDefaultDeclaration.
+ * Used by the wrapper plugin to decide whether default import is safe.
+ * @param {object} ast - Babel AST.
+ * @returns {boolean}
+ */
+function hasDefault(ast) {
+    for (const node of ast.program.body) {
+        if (node.type === "ExportDefaultDeclaration") return true;
+    }
+
+    return false;
+}
+
+/**
+ * Unwraps HOC patterns like memo() and forwardRef() to find the inner function.
+ * @param {object} callNode - CallExpression AST node.
+ * @param {import("@babel/traverse").NodePath} callPath - Babel path for the call.
+ * @returns {import("@babel/traverse").NodePath|null}
+ */
+function unwrapHOC(callNode, callPath) {
+    const callee = callNode.callee;
+
+    if (!callee) return null;
+
+    const calleeName = callee.type === "Identifier"
+        ? callee.name
+        : callee.type === "MemberExpression" && callee.property?.name
+            ? callee.property.name
+            : null;
+
+    if (!calleeName || !["memo", "forwardRef"].includes(calleeName)) return null;
+
+    const arg = callNode.arguments[0];
+    if (!arg) return null;
+
+    if (arg.type === "ArrowFunctionExpression" || arg.type === "FunctionExpression" || arg.type === "FunctionDeclaration") {
+        return callPath.get("arguments.0");
+    }
+
+    // Nested HOC: memo(forwardRef(fn)) → recurse into inner CallExpression
+    if (arg.type === "CallExpression") {
+        return unwrapHOC(arg, callPath.get("arguments.0"));
+    }
+
+    return null;
+}
+
+/**
+ * Extracts prop usage from a component function path.
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @returns {object|null}
+ */
+function extractPropUsage(funcPath) {
+    const params = funcPath.node.params;
+
+    if (!params || params.length === 0) return {};
+
+    const firstParam = params[0];
+
+    // ({ name, admin }) => ...
+    if (firstParam.type === "ObjectPattern") {
+        return analyzeObjectPattern(firstParam, funcPath);
+    }
+
+    // (props) => ...
+    if (firstParam.type === "Identifier") {
+        return analyzePropsIdentifier(firstParam.name, funcPath);
+    }
+
+    // (props: Props) with TypeAnnotation — underlying is still Identifier or ObjectPattern
+    if (firstParam.type === "AssignmentPattern") {
+        const left = firstParam.left;
+
+        if (left.type === "ObjectPattern") {
+            return analyzeObjectPattern(left, funcPath);
+        }
+
+        if (left.type === "Identifier") {
+            return analyzePropsIdentifier(left.name, funcPath);
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Analyzes destructured props: ({ name, admin, ...rest }) => ...
+ * @param {object} pattern - ObjectPattern AST node.
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @returns {object|null}
+ */
+function analyzeObjectPattern(pattern, funcPath) {
+    const usage = {};
+    const varsToTrack = [];
+
+    for (const prop of pattern.properties) {
+        // Rest spread: { ...rest } → passthrough (can't determine usage)
+        if (prop.type === "RestElement") return null;
+
+        const key = prop.key?.name || prop.key?.value;
+        if (!key) continue;
+
+        const value = prop.value || prop;
+
+        if (value.type === "Identifier") {
+            // Simple: { admin } or { admin: myAdmin }
+            varsToTrack.push({ key, varName: value.name });
+        }
+        else if (value.type === "ObjectPattern") {
+            // Nested destructuring: { admin: { name, role } }
+            usage[key] = buildNestedDestructureTree(value);
+        }
+        else if (value.type === "AssignmentPattern") {
+            // Default value: { name = "default" }
+            const left = value.left;
+
+            if (left.type === "Identifier") {
+                varsToTrack.push({ key, varName: left.name });
+            }
+            else if (left.type === "ObjectPattern") {
+                usage[key] = buildNestedDestructureTree(left);
+            }
+        }
+    }
+
+    // Track how each destructured variable is used in the function body
+    const bodyStart = funcPath.node.body?.start ?? 0;
+
+    for (const { key, varName } of varsToTrack) {
+        const propUsage = trackVariableAccess(varName, funcPath, bodyStart);
+
+        if (propUsage !== false) {
+            usage[key] = propUsage;
+        }
+    }
+
+    return usage;
+}
+
+/**
+ * Builds usage tree from nested destructuring.
+ * { admin: { name, mfa: { status } } } → { name: true, mfa: { status: true } }
+ * @param {object} pattern - ObjectPattern AST node.
+ * @returns {object|true}
+ */
+function buildNestedDestructureTree(pattern) {
+    const tree = {};
+
+    for (const prop of pattern.properties) {
+        if (prop.type === "RestElement") return true;
+
+        const key = prop.key?.name || prop.key?.value;
+        if (!key) continue;
+
+        const value = prop.value || prop;
+
+        if (value.type === "ObjectPattern") {
+            tree[key] = buildNestedDestructureTree(value);
+        }
+        else {
+            tree[key] = true;
+        }
+    }
+
+    return Object.keys(tree).length > 0 ? tree : true;
+}
+
+/**
+ * Tracks how a variable is accessed in the function body.
+ * Collects MemberExpression chains to build a sub-property tree.
+ *
+ * @param {string} varName - Variable name to track.
+ * @param {import("@babel/traverse").NodePath} funcPath - Function path.
+ * @param {number} bodyStart - Start position of function body.
+ * @returns {object|true} Sub-tree or true (used as whole).
+ */
+function trackVariableAccess(varName, funcPath, bodyStart) {
+    let usedAsWhole = false;
+    const chains = [];
+    const arrayIterations = [];
+
+    funcPath.traverse({
+        Identifier(idPath) {
+            // Skip identifiers before the function body (params, type annotations)
+            if (idPath.node.start < bodyStart) return;
+
+            if (idPath.node.name !== varName) return;
+
+            // Skip type annotations
+            if (isInTypeAnnotation(idPath)) return;
+
+            // Skip if this is a property key (not value): { admin: something }
+            if (idPath.parentPath.isObjectProperty() &&
+                idPath.parentPath.node.key === idPath.node &&
+                !idPath.parentPath.node.computed) {
+                return;
+            }
+
+            // Skip import specifiers
+            if (idPath.parentPath.isImportSpecifier() || idPath.parentPath.isImportDefaultSpecifier()) {
+                return;
+            }
+
+            // Check if part of a MemberExpression chain (including optional chaining ?.)
+            const isMember = idPath.parentPath.isMemberExpression() || idPath.parentPath.isOptionalMemberExpression();
+
+            if (isMember &&
+                idPath.parentPath.node.object === idPath.node &&
+                !idPath.parentPath.node.computed) {
+
+                const chain = collectMemberChain(idPath.parentPath);
+                const outermost = getOutermostMemberExpr(idPath.parentPath);
+
+                // Check for...of: for (const item of varName.items)
+                if (outermost.parentPath.isForOfStatement() &&
+                    outermost.parentPath.node.right === outermost.node) {
+                    const loopVar = extractForOfVariable(outermost.parentPath.node);
+
+                    if (loopVar) {
+                        arrayIterations.push({ prefixChain: chain, loopVar, scopePath: outermost.parentPath });
+                        return;
+                    }
+                }
+
+                const isCallCallee = (outermost.parentPath.isCallExpression() || outermost.parentPath.isOptionalCallExpression()) &&
+                                     outermost.parentPath.node.callee === outermost.node;
+
+                if (isCallCallee) {
+                    const methodName = chain[chain.length - 1];
+
+                    if (ARRAY_METHODS.has(methodName)) {
+                        const prefixChain = chain.slice(0, -1);
+                        const callbacks = collectArrayCallbacks(outermost.parentPath, methodName);
+
+                        if (callbacks.length > 0) {
+                            arrayIterations.push({ prefixChain, callbacks });
+                            return;
+                        }
+
+                        usedAsWhole = true;
+                        return;
+                    }
+
+                    chain.pop();
+                }
+
+                if (chain.length === 0) {
+                    usedAsWhole = true;
+                }
+                else {
+                    chains.push(chain);
+                }
+
+                return;
+            }
+
+            // Check direct for...of: for (const item of varName)
+            if (idPath.parentPath.isForOfStatement() &&
+                idPath.parentPath.node.right === idPath.node) {
+                const loopVar = extractForOfVariable(idPath.parentPath.node);
+
+                if (loopVar) {
+                    arrayIterations.push({ prefixChain: [], loopVar, scopePath: idPath.parentPath });
+                    return;
+                }
+            }
+
+            // Guard/truthy checks (isAdmin && ..., isAdmin ? ... : ...) need the
+            // value itself but not its sub-properties. Mark as whole usage so
+            // boolean props are kept in the filtered output.
+            if (isGuardCheck(idPath)) {
+                usedAsWhole = true;
+                return;
+            }
+
+            // Used directly (as argument, JSX attribute value, assignment, etc.)
+            usedAsWhole = true;
+        }
+    });
+
+    if (usedAsWhole) return true;
+    if (chains.length === 0 && arrayIterations.length === 0) return false;
+
+    const tree = chains.length > 0 ? buildTreeFromChains(chains) : {};
+
+    for (const iteration of arrayIterations) {
+        const elementUsage = processArrayIteration(iteration);
+
+        if (elementUsage === null) return true;
+
+        mergeArrayUsage(tree, iteration.prefixChain, elementUsage);
+    }
+
+    return Object.keys(tree).length > 0 ? tree : false;
+}
+
+/**
+ * Extracts the loop variable from a ForOfStatement node.
+ * Handles: const item, let item, destructured { name, id }.
+ * @param {object} forOfNode - ForOfStatement AST node.
+ * @returns {{type: string, name?: string, pattern?: object}|null}
+ */
+function extractForOfVariable(forOfNode) {
+    const left = forOfNode.left;
+
+    if (left.type !== "VariableDeclaration") return null;
+
+    const id = left.declarations[0]?.id;
+    if (!id) return null;
+
+    if (id.type === "Identifier") return { type: "identifier", name: id.name };
+    if (id.type === "ObjectPattern") return { type: "pattern", pattern: id };
+
+    return null;
+}
+
+/**
+ * Collects all array method callbacks from an initial call and any chained calls.
+ * items.filter(cb1).map(cb2) → [cb1Info, cb2Info]
+ * @param {import("@babel/traverse").NodePath} callExprPath - Initial CallExpression path.
+ * @param {string} methodName - Initial method name.
+ * @returns {Array<{param: object, callbackPath: import("@babel/traverse").NodePath}>}
+ */
+function collectArrayCallbacks(callExprPath, methodName) {
+    const callbacks = [];
+
+    const cb = callExprPath.node.arguments[0];
+
+    if (cb && (cb.type === "ArrowFunctionExpression" || cb.type === "FunctionExpression")) {
+        const pIdx = methodName === "reduce" ? 1 : 0;
+        const param = cb.params?.[pIdx];
+
+        if (param) {
+            callbacks.push({ param, callbackPath: callExprPath.get("arguments.0") });
+        }
+    }
+
+    // Follow chain upward for chained array methods: .filter(cb).map(cb)
+    let current = callExprPath;
+
+    while (current.parentPath.isMemberExpression() &&
+           current.parentPath.node.object === current.node &&
+           !current.parentPath.node.computed) {
+
+        const chainedMethod = current.parentPath.node.property?.name;
+        const gp = current.parentPath.parentPath;
+
+        if (gp.isCallExpression() && gp.node.callee === current.parentPath.node && ARRAY_METHODS.has(chainedMethod)) {
+            const chainedCb = gp.node.arguments[0];
+
+            if (chainedCb && (chainedCb.type === "ArrowFunctionExpression" || chainedCb.type === "FunctionExpression")) {
+                const pIdx = chainedMethod === "reduce" ? 1 : 0;
+                const param = chainedCb.params?.[pIdx];
+
+                if (param) {
+                    callbacks.push({ param, callbackPath: gp.get("arguments.0") });
+                }
+            }
+
+            current = gp;
+        }
+        else {
+            break;
+        }
+    }
+
+    return callbacks;
+}
+
+/**
+ * Processes a collected array iteration (method callbacks or for...of) into element usage.
+ * @param {object} iteration - Collected iteration info.
+ * @returns {object|true|null} Element usage tree, true (whole), or null (unanalyzable).
+ */
+function processArrayIteration(iteration) {
+    if (iteration.callbacks) {
+        let merged = {};
+
+        for (const { param, callbackPath } of iteration.callbacks) {
+            const usage = analyzeCallbackParam(param, callbackPath);
+
+            if (usage === null) return null;
+            if (usage === true) return true;
+
+            merged = mergeUsageTrees(merged, usage);
+        }
+
+        return merged;
+    }
+
+    if (iteration.loopVar) {
+        const bodyStart = iteration.scopePath.node.body?.start ?? 0;
+
+        if (iteration.loopVar.type === "identifier") {
+            const usage = trackVariableAccess(iteration.loopVar.name, iteration.scopePath, bodyStart);
+            return usage === false ? {} : usage;
+        }
+
+        if (iteration.loopVar.type === "pattern") {
+            return buildNestedDestructureTree(iteration.loopVar.pattern);
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Analyzes a callback parameter to extract element property usage.
+ * @param {object} param - Callback parameter AST node.
+ * @param {import("@babel/traverse").NodePath} callbackPath - Callback function path.
+ * @returns {object|true|null} Usage tree, true (whole), or null (unanalyzable).
+ */
+function analyzeCallbackParam(param, callbackPath) {
+    if (param.type === "ObjectPattern") {
+        return buildNestedDestructureTree(param);
+    }
+
+    if (param.type === "Identifier") {
+        const bodyStart = callbackPath.node.body?.start ?? 0;
+        const usage = trackVariableAccess(param.name, callbackPath, bodyStart);
+        return usage === false ? {} : usage;
+    }
+
+    if (param.type === "AssignmentPattern") {
+        const left = param.left;
+
+        if (left.type === "ObjectPattern") return buildNestedDestructureTree(left);
+
+        if (left.type === "Identifier") {
+            const bodyStart = callbackPath.node.body?.start ?? 0;
+            const usage = trackVariableAccess(left.name, callbackPath, bodyStart);
+            return usage === false ? {} : usage;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Merges array element usage into the tree at the correct position.
+ * @param {object} tree - Usage tree to merge into.
+ * @param {string[]} prefixChain - Chain of property names leading to the array.
+ * @param {object|true} elementUsage - Element usage tree.
+ */
+function mergeArrayUsage(tree, prefixChain, elementUsage) {
+    let current = tree;
+
+    for (const key of prefixChain) {
+        if (current[key] === true) return;
+
+        if (!current[key] || typeof current[key] !== "object") {
+            current[key] = {};
+        }
+
+        current = current[key];
+    }
+
+    if (current["[]"]) {
+        current["[]"] = mergeUsageTrees(current["[]"], elementUsage);
+    }
+    else {
+        current["[]"] = elementUsage;
+    }
+}
+
+/**
+ * Collects property names from a MemberExpression chain.
+ * admin.mfa.status → ["mfa", "status"]
+ * @param {import("@babel/traverse").NodePath} memberPath
+ * @returns {string[]}
+ */
+function collectMemberChain(memberPath) {
+    const chain = [];
+    let current = memberPath;
+
+    while ((current.isMemberExpression() || current.isOptionalMemberExpression()) && !current.node.computed) {
+        const propName = current.node.property.name || current.node.property.value;
+        if (!propName) break;
+
+        chain.push(propName);
+
+        const parentIsMember = current.parentPath.isMemberExpression() || current.parentPath.isOptionalMemberExpression();
+
+        if (parentIsMember &&
+            current.parentPath.node.object === current.node &&
+            !current.parentPath.node.computed) {
+            current = current.parentPath;
+        }
+        else {
+            break;
+        }
+    }
+
+    return chain;
+}
+
+/**
+ * Walks up to the outermost MemberExpression in a chain.
+ * @param {import("@babel/traverse").NodePath} memberPath
+ * @returns {import("@babel/traverse").NodePath}
+ */
+function getOutermostMemberExpr(memberPath) {
+    let current = memberPath;
+
+    while ((current.parentPath.isMemberExpression() || current.parentPath.isOptionalMemberExpression()) &&
+           current.parentPath.node.object === current.node) {
+        current = current.parentPath;
+    }
+
+    return current;
+}
+
+/**
+ * Analyzes props accessed via identifier pattern: (props) => props.name
+ * @param {string} propsName - The parameter name (e.g., "props").
+ * @param {import("@babel/traverse").NodePath} funcPath
+ * @returns {object|null}
+ */
+function analyzePropsIdentifier(propsName, funcPath) {
+    let usedAsWhole = false;
+    const chains = [];
+    const arrayIterations = [];
+    const bodyStart = funcPath.node.body?.start ?? 0;
+
+    funcPath.traverse({
+        Identifier(idPath) {
+            if (idPath.node.start < bodyStart) return;
+            if (idPath.node.name !== propsName) return;
+            if (isInTypeAnnotation(idPath)) return;
+
+            // Skip property keys
+            if (idPath.parentPath.isObjectProperty() &&
+                idPath.parentPath.node.key === idPath.node &&
+                !idPath.parentPath.node.computed) {
+                return;
+            }
+
+            // props.X access (including optional chaining props?.X)
+            const isPropsMember = idPath.parentPath.isMemberExpression() || idPath.parentPath.isOptionalMemberExpression();
+
+            if (isPropsMember &&
+                idPath.parentPath.node.object === idPath.node &&
+                !idPath.parentPath.node.computed) {
+
+                const chain = collectMemberChain(idPath.parentPath);
+                const outermost = getOutermostMemberExpr(idPath.parentPath);
+
+                const isCallCallee = (outermost.parentPath.isCallExpression() || outermost.parentPath.isOptionalCallExpression()) &&
+                                     outermost.parentPath.node.callee === outermost.node;
+
+                if (isCallCallee) {
+                    const methodName = chain[chain.length - 1];
+
+                    if (ARRAY_METHODS.has(methodName)) {
+                        const prefixChain = chain.slice(0, -1);
+                        const callbacks = collectArrayCallbacks(outermost.parentPath, methodName);
+
+                        if (callbacks.length > 0) {
+                            arrayIterations.push({ prefixChain, callbacks });
+                            return;
+                        }
+
+                        usedAsWhole = true;
+                        return;
+                    }
+
+                    chain.pop();
+                }
+
+                if (chain.length === 0) {
+                    usedAsWhole = true;
+                }
+                else {
+                    chains.push(chain);
+                }
+
+                return;
+            }
+
+            // props used as a whole (destructured in body, passed as arg, etc.)
+            usedAsWhole = true;
+        }
+    });
+
+    if (usedAsWhole) return null;
+    if (chains.length === 0 && arrayIterations.length === 0) return {};
+
+    const tree = chains.length > 0 ? buildTreeFromChains(chains) : {};
+
+    for (const iteration of arrayIterations) {
+        const elementUsage = processArrayIteration(iteration);
+
+        if (elementUsage === null) return null;
+
+        mergeArrayUsage(tree, iteration.prefixChain, elementUsage);
+    }
+
+    return Object.keys(tree).length > 0 ? tree : {};
+}
+
+/**
+ * Checks if an identifier is used in a guard/truthy check position.
+ * These patterns test existence without reading object contents:
+ *   - data && <jsx>           (LogicalExpression left operand)
+ *   - data ? <a> : <b>        (ConditionalExpression test)
+ *   - !data                    (UnaryExpression !)
+ *   - if (data) { ... }        (IfStatement test)
+ *
+ * @param {import("@babel/traverse").NodePath} idPath
+ * @returns {boolean}
+ */
+function isGuardCheck(idPath) {
+    const parent = idPath.parentPath;
+    const node = parent.node;
+
+    // data && ..., data || ..., data ?? ...
+    if (parent.isLogicalExpression() && node.left === idPath.node) return true;
+
+    // data ? ... : ...
+    if (parent.isConditionalExpression() && node.test === idPath.node) return true;
+
+    // !data
+    if (parent.isUnaryExpression() && node.operator === "!") return true;
+
+    // if (data) { ... }
+    if (parent.isIfStatement() && node.test === idPath.node) return true;
+
+    return false;
+}
+
+/**
+ * Checks if a path is inside a TypeScript type annotation.
+ * @param {import("@babel/traverse").NodePath} idPath
+ * @returns {boolean}
+ */
+function isInTypeAnnotation(idPath) {
+    let current = idPath.parentPath;
+
+    while (current) {
+        const type = current.node?.type;
+        if (!type) break;
+
+        if (type.startsWith("TS") || type === "TypeAnnotation") return true;
+        if (current.isStatement() || current.isFunction() || current.isProgram()) break;
+
+        current = current.parentPath;
+    }
+
+    return false;
+}
+
+/**
+ * Builds a usage tree from an array of property access chains.
+ *
+ * [["admin", "name"], ["admin", "mfa", "status"], ["title"]]
+ * → { admin: { name: true, mfa: { status: true } }, title: true }
+ *
+ * @param {string[][]} chains
+ * @returns {object}
+ */
+function buildTreeFromChains(chains) {
+    const tree = {};
+
+    for (const chain of chains) {
+        let current = tree;
+
+        for (let i = 0; i < chain.length; i++) {
+            const key = chain[i];
+
+            if (i === chain.length - 1) {
+                // Last element — mark as used
+                if (typeof current[key] === "object") {
+                    // Was a sub-tree, but also accessed directly → pass whole value
+                    current[key] = true;
+                }
+                else {
+                    current[key] = true;
+                }
+            }
+            else {
+                // Intermediate — needs to be an object for deeper access
+                if (current[key] === true) {
+                    break; // Already full usage, don't downgrade
+                }
+
+                if (!current[key] || typeof current[key] !== "object") {
+                    current[key] = {};
+                }
+
+                current = current[key];
+            }
+        }
+    }
+
+    return tree;
+}
+
+/**
+ * Extracts translation keys from __() and lang() calls in the AST.
+ * Returns an array of string literal keys, or null if any dynamic key is found.
+ * @param {object} ast - Babel AST.
+ * @returns {string[]|null}
+ */
+function extractTranslationKeys(ast) {
+    const keys = new Set();
+    let hasDynamic = false;
+
+    _traverse(ast, {
+        CallExpression(p) {
+            const callee = p.node.callee;
+
+            if (callee.type !== "Identifier" || (callee.name !== "__" && callee.name !== "lang")) return;
+
+            const firstArg = p.node.arguments[0];
+
+            if (!firstArg) return;
+
+            if (firstArg.type === "StringLiteral") {
+                keys.add(firstArg.value);
+            }
+            else {
+                hasDynamic = true;
+            }
+        }
+    });
+
+    if (hasDynamic) return null;
+    if (keys.size === 0) return [];
+
+    return [...keys];
+}
+
+export default PropUsageAnalyzer;