pyjsclear 0.1.0__py3-none-any.whl

pyjsclear/transforms/unused_vars.py

@@ -0,0 +1,111 @@
+"""Remove unreferenced variables."""
+
+from ..scope import build_scope_tree
+from ..traverser import REMOVE
+from ..traverser import traverse
+from ..utils.ast_helpers import get_child_keys
+from .base import Transform
+
+
+_SIDE_EFFECT_TYPES = frozenset(
+    {
+        'CallExpression',
+        'NewExpression',
+        'AssignmentExpression',
+        'UpdateExpression',
+    }
+)
+_PURE_TYPES = frozenset(
+    {
+        'Literal',
+        'Identifier',
+        'ThisExpression',
+        'ArrayExpression',
+        'ObjectExpression',
+        'FunctionExpression',
+        'ArrowFunctionExpression',
+    }
+)
+
+
+class UnusedVariableRemover(Transform):
+    """Remove variables with 0 references after other transforms."""
+
+    rebuild_scope = True
+
+    def execute(self):
+        scope_tree, _ = build_scope_tree(self.ast)
+        declarators_to_remove = set()
+        functions_to_remove = set()
+        self._collect_unused(scope_tree, declarators_to_remove, functions_to_remove)
+        if not declarators_to_remove and not functions_to_remove:
+            return False
+        self._batch_remove(declarators_to_remove, functions_to_remove)
+        return self.has_changed()
+
+    def _collect_unused(self, scope, declarators, functions):
+        skip_global = scope.parent is None
+
+        for name, binding in scope.bindings.items():
+            if binding.references or binding.kind == 'param':
+                continue
+            if skip_global and not name.startswith('_0x'):
+                continue
+            node = binding.node
+            if not isinstance(node, dict):
+                continue
+
+            node_type = node.get('type')
+            if node_type == 'VariableDeclarator':
+                init = node.get('init')
+                if not init or not self._has_side_effects(init):
+                    declarators.add(id(node))
+            elif node_type == 'FunctionDeclaration':
+                functions.add(id(node))
+
+        for child in scope.children:
+            self._collect_unused(child, declarators, functions)
+
+    def _batch_remove(self, declarators_to_remove, functions_to_remove):
+        """Remove all collected unused declarations in a single traversal."""
+
+        def enter(node, parent, key, index):
+            node_type = node.get('type')
+            if node_type == 'FunctionDeclaration' and id(node) in functions_to_remove:
+                self.set_changed()
+                return REMOVE
+            if node_type != 'VariableDeclaration':
+                return
+            decls = node.get('declarations')
+            if not decls:
+                return
+            new_decls = [d for d in decls if id(d) not in declarators_to_remove]
+            if len(new_decls) == len(decls):
+                return
+            self.set_changed()
+            if not new_decls:
+                return REMOVE
+            node['declarations'] = new_decls
+
+        traverse(self.ast, {'enter': enter})
+
+    def _has_side_effects(self, node):
+        """Conservative check for side effects in an expression."""
+        if not isinstance(node, dict):
+            return False
+        node_type = node.get('type', '')
+        if node_type in _SIDE_EFFECT_TYPES:
+            return True
+        if node_type in _PURE_TYPES:
+            return False
+        # For binary/unary/etc, recurse into children
+        for key in get_child_keys(node):
+            child = node.get(key)
+            if child is None:
+                continue
+            if isinstance(child, list):
+                if any(isinstance(item, dict) and self._has_side_effects(item) for item in child):
+                    return True
+            elif isinstance(child, dict) and self._has_side_effects(child):
+                return True
+        return False

pyjsclear/traverser.py

@@ -0,0 +1,195 @@
+"""ESTree AST traversal with visitor pattern."""
+
+from .utils.ast_helpers import _CHILD_KEYS
+from .utils.ast_helpers import get_child_keys
+
+
+# Sentinel to signal node removal
+REMOVE = object()
+# Sentinel to skip traversing children
+SKIP = object()
+
+# Local aliases for hot-path performance (~15% faster traversal)
+_dict = dict
+_list = list
+_isinstance = isinstance
+
+
+def traverse(node, visitor):
+    """Traverse an ESTree AST calling visitor callbacks.
+
+    visitor should be a dict or object with optional 'enter' and 'exit' callables.
+    Each callback receives (node, parent, key, index) and can return:
+      - None: continue normally
+      - REMOVE: remove this node from parent
+      - SKIP: (enter only) skip traversing children
+      - a dict (node): replace this node with the returned node
+    """
+    if _isinstance(visitor, _dict):
+        enter_fn = visitor.get('enter')
+        exit_fn = visitor.get('exit')
+    else:
+        enter_fn = getattr(visitor, 'enter', None)
+        exit_fn = getattr(visitor, 'exit', None)
+
+    child_keys_map = _CHILD_KEYS
+    _REMOVE = REMOVE
+    _SKIP = SKIP
+
+    def _visit(current_node, parent, key, index):
+        node_type = current_node.get('type')
+        if node_type is None:
+            return current_node
+
+        # Enter
+        if enter_fn:
+            result = enter_fn(current_node, parent, key, index)
+            if result is _REMOVE:
+                return _REMOVE
+            if result is _SKIP:
+                if not exit_fn:
+                    return current_node
+                exit_result = exit_fn(current_node, parent, key, index)
+                if exit_result is _REMOVE:
+                    return _REMOVE
+                if _isinstance(exit_result, _dict) and 'type' in exit_result:
+                    return exit_result
+                return current_node
+            if _isinstance(result, _dict) and 'type' in result:
+                current_node = result
+                if parent is not None:
+                    if index is not None:
+                        parent[key][index] = current_node
+                    else:
+                        parent[key] = current_node
+
+        # Visit children
+        child_keys = child_keys_map.get(current_node.get('type'))
+        if child_keys is None:
+            child_keys = get_child_keys(current_node)
+        for child_key in child_keys:
+            child = current_node.get(child_key)
+            if child is None:
+                continue
+            if _isinstance(child, _list):
+                i = 0
+                while i < len(child):
+                    item = child[i]
+                    if _isinstance(item, _dict) and 'type' in item:
+                        result = _visit(item, current_node, child_key, i)
+                        if result is _REMOVE:
+                            child.pop(i)
+                            continue
+                        elif result is not item:
+                            child[i] = result
+                    i += 1
+            elif _isinstance(child, _dict) and 'type' in child:
+                result = _visit(child, current_node, child_key, None)
+                if result is _REMOVE:
+                    current_node[child_key] = None
+                elif result is not child:
+                    current_node[child_key] = result
+
+        # Exit
+        if exit_fn:
+            result = exit_fn(current_node, parent, key, index)
+            if result is _REMOVE:
+                return _REMOVE
+            if _isinstance(result, _dict) and 'type' in result:
+                return result
+
+        return current_node
+
+    _visit(node, None, None, None)
+
+
+def simple_traverse(node, callback):
+    """Simple traversal that calls callback(node, parent) for every node.
+    No replacement support - just visiting.
+    """
+    child_keys_map = _CHILD_KEYS
+
+    def _visit(current_node, parent):
+        node_type = current_node.get('type')
+        if node_type is None:
+            return
+        callback(current_node, parent)
+        child_keys = child_keys_map.get(node_type)
+        if child_keys is None:
+            child_keys = get_child_keys(current_node)
+        for key in child_keys:
+            child = current_node.get(key)
+            if child is None:
+                continue
+            if _isinstance(child, _list):
+                for item in child:
+                    if _isinstance(item, _dict) and 'type' in item:
+                        _visit(item, current_node)
+            elif _isinstance(child, _dict) and 'type' in child:
+                _visit(child, current_node)
+
+    _visit(node, None)
+
+
+def collect_nodes(ast, node_type):
+    """Collect all nodes of a given type."""
+    result = []
+
+    def cb(node, parent):
+        if node.get('type') == node_type:
+            result.append(node)
+
+    simple_traverse(ast, cb)
+    return result
+
+
+class _FoundParent(Exception):
+    """Raised to short-circuit find_parent search."""
+
+    __slots__ = ('value',)
+
+    def __init__(self, value):
+        self.value = value
+
+
+def find_parent(ast, target_node):
+    """Find the parent of a node in the AST. Returns (parent, key, index) or None."""
+
+    def _visit(node):
+        if not isinstance(node, dict) or 'type' not in node:
+            return
+        for child_key in get_child_keys(node):
+            child = node.get(child_key)
+            if child is None:
+                continue
+            if isinstance(child, list):
+                for i, item in enumerate(child):
+                    if item is target_node:
+                        raise _FoundParent((node, child_key, i))
+                    _visit(item)
+            elif isinstance(child, dict):
+                if child is target_node:
+                    raise _FoundParent((node, child_key, None))
+                _visit(child)
+
+    try:
+        _visit(ast)
+    except _FoundParent as found:
+        return found.value
+    return None
+
+
+def replace_in_parent(parent, key, index, new_node):
+    """Replace a node within its parent."""
+    if index is not None:
+        parent[key][index] = new_node
+    else:
+        parent[key] = new_node
+
+
+def remove_from_parent(parent, key, index):
+    """Remove a node from its parent."""
+    if index is not None:
+        parent[key].pop(index)
+    else:
+        parent[key] = None

pyjsclear/utils/ast_helpers.py

@@ -0,0 +1,257 @@
+"""AST helper utilities for ESTree nodes."""
+
+import copy
+import re
+
+
+def deep_copy(node):
+    """Deep copy an AST node."""
+    return copy.deepcopy(node)
+
+
+def is_literal(node):
+    """Check if node is a Literal."""
+    return isinstance(node, dict) and node.get('type') == 'Literal'
+
+
+def is_identifier(node):
+    """Check if node is an Identifier."""
+    return isinstance(node, dict) and node.get('type') == 'Identifier'
+
+
+def is_string_literal(node):
+    """Check if node is a string Literal."""
+    return is_literal(node) and isinstance(node.get('value'), str)
+
+
+def is_numeric_literal(node):
+    """Check if node is a numeric Literal."""
+    return is_literal(node) and isinstance(node.get('value'), (int, float))
+
+
+def is_boolean_literal(node):
+    """Check if node is a boolean-ish literal (true/false or !0/!1)."""
+    return is_literal(node) and isinstance(node.get('value'), bool)
+
+
+def is_null_literal(node):
+    """Check if node is null literal."""
+    return is_literal(node) and node.get('value') is None and node.get('raw') == 'null'
+
+
+def is_undefined(node):
+    """Check if node represents undefined."""
+    return is_identifier(node) and node.get('name') == 'undefined'
+
+
+def get_literal_value(node):
+    """Extract the value from a literal node. Returns (value, True) or (None, False)."""
+    if not is_literal(node):
+        return None, False
+    return node.get('value'), True
+
+
+def make_literal(value, raw=None):
+    """Create a Literal AST node."""
+    if raw is not None:
+        return {'type': 'Literal', 'value': value, 'raw': raw}
+
+    match value:
+        case str():
+            escaped = value.replace('\\', '\\\\')
+            escaped = escaped.replace('"', '\\"')
+            escaped = escaped.replace('\n', '\\n')
+            escaped = escaped.replace('\r', '\\r')
+            escaped = escaped.replace('\t', '\\t')
+            escaped = escaped.replace('\0', '\\0')
+            raw = f'"{escaped}"'
+        case bool():
+            raw = 'true' if value else 'false'
+        case int() | float():
+            if isinstance(value, float) and value == int(value) and not (value == 0 and str(value).startswith('-')):
+                raw = str(int(value))
+            else:
+                raw = str(value)
+        case None:
+            raw = 'null'
+        case _:
+            raw = str(value)
+    return {'type': 'Literal', 'value': value, 'raw': raw}
+
+
+def make_identifier(name):
+    """Create an Identifier AST node."""
+    return {'type': 'Identifier', 'name': name}
+
+
+def make_expression_statement(expr):
+    """Wrap an expression in an ExpressionStatement."""
+    return {'type': 'ExpressionStatement', 'expression': expr}
+
+
+def make_block_statement(body):
+    """Create a BlockStatement."""
+    return {'type': 'BlockStatement', 'body': body}
+
+
+def make_var_declaration(name, init=None, kind='var'):
+    """Create a VariableDeclaration with a single declarator."""
+    return {
+        'type': 'VariableDeclaration',
+        'declarations': [{'type': 'VariableDeclarator', 'id': make_identifier(name), 'init': init}],
+        'kind': kind,
+    }
+
+
+_IDENT_RE = re.compile(r'^[a-zA-Z_$][a-zA-Z0-9_$]*$')
+
+
+def is_valid_identifier(name):
+    """Check if a string is a valid JS identifier (for obj.prop access)."""
+    if not isinstance(name, str) or not name:
+        return False
+    return bool(_IDENT_RE.match(name))
+
+
+_CHILD_KEYS = {
+    'Program': ('body',),
+    'ExpressionStatement': ('expression',),
+    'BlockStatement': ('body',),
+    'VariableDeclaration': ('declarations',),
+    'VariableDeclarator': ('id', 'init'),
+    'FunctionDeclaration': ('id', 'params', 'body'),
+    'FunctionExpression': ('id', 'params', 'body'),
+    'ArrowFunctionExpression': ('params', 'body'),
+    'ReturnStatement': ('argument',),
+    'IfStatement': ('test', 'consequent', 'alternate'),
+    'WhileStatement': ('test', 'body'),
+    'DoWhileStatement': ('test', 'body'),
+    'ForStatement': ('init', 'test', 'update', 'body'),
+    'ForInStatement': ('left', 'right', 'body'),
+    'ForOfStatement': ('left', 'right', 'body'),
+    'SwitchStatement': ('discriminant', 'cases'),
+    'SwitchCase': ('test', 'consequent'),
+    'BreakStatement': ('label',),
+    'ContinueStatement': ('label',),
+    'LabeledStatement': ('label', 'body'),
+    'ThrowStatement': ('argument',),
+    'TryStatement': ('block', 'handler', 'finalizer'),
+    'CatchClause': ('param', 'body'),
+    'BinaryExpression': ('left', 'right'),
+    'LogicalExpression': ('left', 'right'),
+    'UnaryExpression': ('argument',),
+    'UpdateExpression': ('argument',),
+    'AssignmentExpression': ('left', 'right'),
+    'MemberExpression': ('object', 'property'),
+    'CallExpression': ('callee', 'arguments'),
+    'NewExpression': ('callee', 'arguments'),
+    'ConditionalExpression': ('test', 'consequent', 'alternate'),
+    'SequenceExpression': ('expressions',),
+    'ArrayExpression': ('elements',),
+    'ObjectExpression': ('properties',),
+    'Property': ('key', 'value'),
+    'SpreadElement': ('argument',),
+    'TemplateLiteral': ('quasis', 'expressions'),
+    'TaggedTemplateExpression': ('tag', 'quasi'),
+    'TemplateElement': (),
+    'AssignmentPattern': ('left', 'right'),
+    'ArrayPattern': ('elements',),
+    'ObjectPattern': ('properties',),
+    'RestElement': ('argument',),
+    'ClassDeclaration': ('id', 'superClass', 'body'),
+    'ClassExpression': ('id', 'superClass', 'body'),
+    'ClassBody': ('body',),
+    'MethodDefinition': ('key', 'value'),
+    'YieldExpression': ('argument',),
+    'AwaitExpression': ('argument',),
+    'EmptyStatement': (),
+    'Literal': (),
+    'Identifier': (),
+    'ThisExpression': (),
+}
+
+_SKIP_KEYS = frozenset(
+    (
+        'type',
+        'raw',
+        'value',
+        'name',
+        'operator',
+        'kind',
+        'computed',
+        'method',
+        'shorthand',
+        'prefix',
+        'async',
+        'generator',
+        'static',
+        'sourceType',
+        'start',
+        'end',
+        'loc',
+        'range',
+        'directive',
+        'regex',
+    )
+)
+
+
+def get_child_keys(node):
+    """Get keys of a node that may contain child nodes/arrays."""
+    if not isinstance(node, dict) or 'type' not in node:
+        return ()
+    node_type = node['type']
+    keys = _CHILD_KEYS.get(node_type)
+    if keys is not None:
+        return keys
+    # Fallback: return all keys that look like they might contain nodes
+    return [
+        k
+        for k, v in node.items()
+        if k not in _SKIP_KEYS
+        and not (k == 'expression' and node_type != 'ExpressionStatement')
+        and isinstance(v, (dict, list))
+    ]
+
+
+def replace_identifiers(node, param_map):
+    """Replace Identifier nodes whose names are in param_map with deep copies.
+
+    Skips non-computed property names in MemberExpressions.
+    """
+    if not isinstance(node, dict) or 'type' not in node:
+        return
+    for key in get_child_keys(node):
+        child = node.get(key)
+        if child is None:
+            continue
+        is_noncomputed_prop = key == 'property' and node.get('type') == 'MemberExpression' and not node.get('computed')
+        if isinstance(child, list):
+            for i, item in enumerate(child):
+                if isinstance(item, dict) and item.get('type') == 'Identifier':
+                    if not is_noncomputed_prop and item.get('name', '') in param_map:
+                        child[i] = copy.deepcopy(param_map[item['name']])
+                elif isinstance(item, dict) and 'type' in item:
+                    replace_identifiers(item, param_map)
+        elif isinstance(child, dict):
+            if child.get('type') == 'Identifier':
+                if not is_noncomputed_prop and child.get('name', '') in param_map:
+                    node[key] = copy.deepcopy(param_map[child['name']])
+            elif 'type' in child:
+                replace_identifiers(child, param_map)
+
+
+def nodes_equal(a, b):
+    """Check if two AST nodes are structurally equal (ignoring position info)."""
+    if type(a) != type(b):
+        return False
+    match a:
+        case dict():
+            keys_a = {k for k in a if k not in ('start', 'end', 'loc', 'range')}
+            keys_b = {k for k in b if k not in ('start', 'end', 'loc', 'range')}
+            if keys_a != keys_b:
+                return False
+            return all(nodes_equal(a[k], b[k]) for k in keys_a)
+        case list():
+            return len(a) == len(b) and all(nodes_equal(x, y) for x, y in zip(a, b))
+    return a == b