Code quality, Python 3.11 compat, and perf optimizations (#11)

* Enforce coding standards and add docstrings across entire codebase

- Expand all short variable names (init, expr, stmt, prop, obj, args, etc.)
- Add StrEnum for constant strings (BindingKind, node types, operators)
- Replace if/elif chains with match statements (~20 files)
- Reduce nesting via early exits and extracted helper functions
- Add type hints to all function signatures using '|' union syntax
- Add from __future__ import annotations to all modules
- Add concise docstrings to every function, class, and method
- Enforce single quotes for strings, double quotes for docstrings
- Update tests to match renamed symbols and heuristic outputs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

black && isort

* Fix Python 3.11 compatibility: replace type statement with plain aliases

The `type X = ...` syntax requires Python 3.12+, but CI tests on 3.11.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix review issues: revert over-engineering, remove perf regressions

- Revert IntEnum+match/case in traverser hot path back to plain int
  constants with if/elif (avoids enum dispatch overhead)
- Revert sys.modules indirection in _run_pre_passes to direct calls
- Remove BindingKind StrEnum; revert to plain string comparisons
- Revert unnecessary variable renames (parser, __main__, _fast_to_dict)
- Remove duplicate _write_output helpers; inline the I/O
- Remove ~56 trivial docstrings that just restate function names
- Restore sample.deobfuscated.js to match main (revert VariableRenamer
  behavioral change that renamed str→string, arr→array, etc.)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Optimize ConstantProp, ExpressionSimplifier, and _count_nodes

Profiled 525 files (25 regression + 500 random from dataset).
Total time improved from 20.6s to 18.4s (11% faster).

ConstantProp (30x faster on large files):
- _find_and_remove_declarator did a full AST traversal per removed
  binding (O(n*k)). Batched into single pass with set lookup (O(n)).
- vue.esm.browser.js: 0.561s → 0.012s for this transform alone.

ExpressionSimplifier (2.2x faster):
- Merged 5 separate traverse() calls into 2 (one combined pass for
  unary/binary/conditional/await/comma + one for method calls).

_count_nodes:
- Replaced callback-based simple_traverse with direct iterative loop,
  eliminating per-node function call overhead.

_fast_to_dict (parser):
- Converted recursive esprima-to-dict conversion to stack-based
  iteration to avoid recursion overhead on large ASTs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* bump version

* Add .gitignore and reference Kaggle dataset in README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update snapshot to match new VariableRenamer heuristics

The coding standards commit added response-like, path-like, and other
usage-based rename hints to VariableRenamer. Regenerate the expected
output snapshot to match.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: itamarga

.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.idea/
+.nodeenv/
+.venv/
+uv.lock
+tests/resources/jsimplifier
+tests/resources/obfuscated-javascript-dataset

README.md

@@ -94,5 +94,6 @@ See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) and
 [NOTICE](NOTICE) for full attribution.
 
 Test samples include obfuscated JavaScript from the
-[JSIMPLIFIER dataset](https://zenodo.org/records/17531662) (GPL-3.0),
+[JSIMPLIFIER dataset](https://zenodo.org/records/17531662) (GPL-3.0)
+and the [Obfuscated JavaScript Dataset](https://www.kaggle.com/datasets/fanbyprinciple/obfuscated-javascript-dataset),
 used solely for evaluation purposes.

pyjsclear/__init__.py

@@ -5,14 +5,18 @@
 Python package.
 """
 
+from pathlib import Path
+
 from .deobfuscator import Deobfuscator
 
 
-__version__ = '0.1.4'
+__all__ = ['Deobfuscator', 'deobfuscate', 'deobfuscate_file']
+
+__version__ = '0.1.5'
 
 
 def deobfuscate(code: str, max_iterations: int = 50) -> str:
-    """Deobfuscate JavaScript code. Returns cleaned source.
+    """Deobfuscate JavaScript code and return cleaned source.
 
     Args:
         code: JavaScript source code string.
@@ -24,7 +28,11 @@ def deobfuscate(code: str, max_iterations: int = 50) -> str:
     return Deobfuscator(code, max_iterations=max_iterations).execute()
 
 
-def deobfuscate_file(input_path: str, output_path: str | None = None, max_iterations: int = 50) -> str | bool:
+def deobfuscate_file(
+    input_path: str | Path,
+    output_path: str | Path | None = None,
+    max_iterations: int = 50,
+) -> str | bool:
     """Deobfuscate a JavaScript file.
 
     Args:
@@ -40,8 +48,9 @@ def deobfuscate_file(input_path: str, output_path: str | None = None, max_iterat
 
     result = deobfuscate(code, max_iterations=max_iterations)
 
-    if output_path:
-        with open(output_path, 'w') as output_file:
-            output_file.write(result)
-        return result != code
-    return result
+    if not output_path:
+        return result
+
+    with open(output_path, 'w') as output_file:
+        output_file.write(result)
+    return result != code

pyjsclear/__main__.py

@@ -7,6 +7,7 @@
 
 
 def main() -> None:
+    """Parse CLI arguments and run the deobfuscator."""
     parser = argparse.ArgumentParser(description='Deobfuscate JavaScript files.')
     parser.add_argument('input', help='Input JS file (use - for stdin)')
     parser.add_argument('-o', '--output', help='Output file (default: stdout)')