da

utils/name_gen.py

@@ -1,14 +1,29 @@
+"""
+@file utils/name_gen.py
+@brief Obfuscated identifier name generator.
+@details Provides NameGenerator that yields high-entropy-looking identifiers
+         and ensures uniqueness across a transformation session.
+"""
 import itertools
 from typing import Iterator, Set
 
 class NameGenerator:
+    """
+    @brief Generates unique obfuscated identifiers.
+    @details Uses patterned Cartesian products to create long, confusing names and
+             tracks used names to avoid collisions.
+    """
     def __init__(self):
+        """
+        @brief Initialize internal iterator and used-name set.
+        """
         self._name_iterator = self._create_iterator()
         self.used_names = set()
     
     def _create_iterator(self) -> Iterator[str]:
         """
-        Generates obfuscated names like: vIl1lO0o0Z2z2...
+        @brief Iterator producing obfuscated identifier candidates.
+        @return Iterator[str] Infinite stream of names such as vIl1lO0o0Z2z2...
         """
         patterns = ['Il1l', 'O0o0', 'Z2z2', 'S5s5', 'B8b8', 'Q9q9']
         for length in itertools.count(2):  # Start with length=2, continue forever
@@ -17,7 +32,8 @@ class NameGenerator:
 
     def generate_name(self) -> str:
         """
-        Get a fresh unique variable name.
+        @brief Produce a fresh, unique obfuscated name.
+        @return str Name guaranteed not to have been produced before by this instance.
         """
         while True:
             candidate = next(self._name_iterator)