da

obfuscator.py

@@ -1,3 +1,11 @@
+"""
+@file obfuscator.py
+@brief Core engine for OMG-Fuscator.
+@details Orchestrates the full obfuscation pipeline: symbol analysis and renaming,
+         string encryption, control-flow flattening, and junk code insertion.
+         Provides debug instrumentation and JSON reporting when enabled.
+"""
+
 import ast
 import random
 import json
@@ -15,6 +23,12 @@ from transformers.class_mapper import apply_class_mapping
 
 
 class AdvancedObfuscator:
+    """
+    @brief Core obfuscation engine orchestrating all transformations.
+    @details Coordinates name generation, symbol tree construction, AST transformations
+             for renaming and string encryption, control-flow flattening, and final
+             code generation with junk injection. Optionally records detailed debug data.
+    """
     def __init__(self, debug_mode=False):
         self.used_names = set()
         self.name_generator = NameGenerator()
@@ -49,7 +63,11 @@ class AdvancedObfuscator:
         }
 
     def log_debug(self, category, data):
-        """Log debugging information if debug mode is on."""
+        """
+        @brief Append a structured debug entry if debug mode is enabled.
+        @param category Logical stage or component name.
+        @param data Arbitrary JSON-serializable payload to record.
+        """
         if self.debug_mode:
             self.debug_data["transformations"].append({
                 "stage": category,
@@ -58,7 +76,11 @@ class AdvancedObfuscator:
             })
     
     def detect_issues(self):
-        """Detect potential issues in the obfuscation process."""
+        """
+        @brief Run integrity checks and record any issues to debug data.
+        @details Aggregates issues from the symbol tree and legacy name-collision
+                 checks to help diagnose transformation inconsistencies.
+        """
         if not self.debug_mode:
             return
             
@@ -92,7 +114,9 @@ class AdvancedObfuscator:
     
     def _build_symbol_tree(self, tree: ast.AST) -> SymbolTree:
         """
-        Build a comprehensive symbol tree from the AST for better tracking and renaming.
+        @brief Build a global symbol tree from the parsed AST.
+        @param tree Parsed AST of the input source.
+        @return SymbolTree Populated symbol tree with rename mappings and metadata.
         """
         if self.debug_mode:
             self.log_debug("symbol_tree_building", "Building global symbol tree")
@@ -141,8 +165,9 @@ class AdvancedObfuscator:
 
     def _rename_and_encrypt(self, tree: ast.AST) -> ast.AST:
         """
-        Transform the AST to rename variables and encrypt string literals.
-        Uses the symbol tree for consistent renaming.
+        @brief Rename identifiers and encrypt string literals in the AST.
+        @param tree Input AST prior to control-flow transformations.
+        @return ast.AST Transformed AST with consistent renames and encrypted strings.
         """
         # First, build a comprehensive symbol tree
         self.symbol_tree = self._build_symbol_tree(tree)
@@ -170,7 +195,9 @@ class AdvancedObfuscator:
 
     def _flatten_control_flow(self, tree: ast.AST) -> ast.AST:
         """
-        Flatten control flow by rewriting function/module bodies into a while-based dispatch.
+        @brief Flatten control flow into a state-machine dispatch form.
+        @param tree AST after renaming/encryption.
+        @return ast.AST Transformed AST with flattened control flow.
         """
         flattener = ControlFlowFlattener(debug_mode=self.debug_mode)
         tree = flattener.visit(tree)
@@ -184,8 +211,9 @@ class AdvancedObfuscator:
 
     def _generate_final_code(self, tree: ast.AST) -> str:
         """
-        Convert the final AST to code, and optionally insert junk snippets 
-        among lines to obscure readability.
+        @brief Generate final Python source from the AST and inject junk code.
+        @param tree AST after all transformations.
+        @return str Final obfuscated Python source code.
         """
         lines = ast.unparse(tree).split('\n')
         in_multiline = False
@@ -249,7 +277,9 @@ class AdvancedObfuscator:
 
     def obfuscate(self, code: str) -> str:
         """
-        Main method to obfuscate the given code.
+        @brief End-to-end obfuscation entry point.
+        @param code Original Python source code.
+        @return str Obfuscated Python source code.
         """
         tree = ast.parse(code)