Claude/refactor sol2ts transpiler yp1ez (#55)

* Refactor sol2ts transpiler into modular architecture

Split the monolithic 6,065-line sol2ts.py into a modular structure:

- transpiler/lexer/ - Tokenization (tokens.py, lexer.py)
  - TokenType enum, Token dataclass
  - Keyword/operator mappings
  - Lexer class

- transpiler/parser/ - AST and parsing (ast_nodes.py, parser.py)
  - All AST node dataclasses (SourceUnit, ContractDefinition, etc.)
  - Recursive descent parser

- transpiler/types/ - Type system (registry.py, mappings.py)
  - TypeRegistry for cross-file type discovery
  - Solidity-to-TypeScript type mappings
  - Default value helpers

- transpiler/codegen/ - Code generation helpers (yul.py, abi.py, context.py)
  - YulTranspiler for inline assembly
  - AbiTypeInferer for ABI encoding
  - CodeGenerationContext for state management

The original sol2ts.py is preserved for backward compatibility.
New code can import from the modules directly:
  from transpiler.lexer import Lexer
  from transpiler.parser import Parser
  from transpiler.types import TypeRegistry

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Complete modular refactoring of sol2ts transpiler

Decompose the monolithic TypeScriptCodeGenerator into focused generator classes:
- BaseGenerator: Shared utilities for all generators
- TypeConverter: Solidity to TypeScript type conversions
- ExpressionGenerator: Expression AST code generation
- StatementGenerator: Statement AST code generation
- FunctionGenerator: Function/constructor generation
- DefinitionGenerator: Struct/enum/constant generation
- ImportGenerator: Import statement generation
- ContractGenerator: Contract class generation
- generator.py: Main orchestrator coordinating all generators

Benefits:
- Single responsibility for each generator class
- Easier testing and maintenance of individual components
- Cleaner separation of concerns
- Total 116 Solidity files transpiled successfully in testing

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Fix ABI type inference for method return types, finalize modular refactoring

Changes:
- Add current_method_return_types tracking in CodeGenerationContext
- Populate method return types in ContractGenerator._setup_contract_context
- Fix ExpressionGenerator._infer_single_abi_type to lookup method return types
- Update test_transpiler.py to use modular imports
- Replace old 6,065-line sol2ts.py with new 264-line modular version
- Update transpiler/__init__.py exports for new module structure

All 8 unit tests pass and 111 Solidity files transpile successfully.

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Add ts-output/ to gitignore

Generated TypeScript output should not be committed.

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Add metadata generation for factories.ts dependency injection

- Create MetadataExtractor to collect contract info from ASTs
- Create FactoryGenerator to produce factories.ts with container registrations
- Integrate metadata generation with --emit-metadata flag
- Auto-generate interface aliases (IEngine -> Engine, etc.)
- Auto-generate lazy singletons with constructor dependencies

All 38 TypeScript tests now pass (previously 31 passed, 1 suite failed).

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Enable previously skipped tests for SignedMatchmaker and GachaTeamRegistry

Both modules now import successfully with the runtime replacements
for EIP712 and Ownable. All 40 tests pass.

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Replace CHANGELOG.md with README.md documenting modular architecture

- Document new module structure (lexer/, parser/, types/, codegen/)
- Document code generator architecture with specialized generators
- Update test counts (40 TypeScript tests, 8 Python tests)
- Document factories.ts generation with --emit-metadata
- Preserve clear, no-frills documentation style

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Refactor parser.py to reduce repetition with DRY helpers

Add utility methods:
- _parse_binary_op(): Generic left-associative binary operator parsing
- parse_comma_separated(): Parse comma-separated lists with end token
- parse_storage_location(): Parse storage/memory/calldata
- skip_balanced(): Skip balanced bracket pairs (parens, braces)

Apply to simplify:
- 10 binary operator methods now use _parse_binary_op helper
- Event/error/function parameters use parse_comma_separated
- State variable/function attributes use token->value dictionaries
- Function skip, try/catch, base contracts use skip_balanced

All 40 TypeScript tests and Python unit tests pass.

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Apply DRY refactoring to codegen modules and fix types/ naming conflict

- expression.py: Extract _resolve_abi_base_type() and _infer_expression_type()
  to share logic between ABI type inference methods (~80 lines reduced)
- statement.py: Extract _generate_body_statements() for loop body generation
- function.py: Extract _get_visibility_modifier() and _get_static_modifier()
- Rename types/ to type_system/ to avoid shadowing Python's standard library

All 40 TypeScript tests and 8 Python unit tests pass.

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Fix bigint index type error and single-file import path calculation

- contract.py: Convert non-string mapping keys to String() for Record indexing
  Fixes TS2538: Type 'bigint' cannot be used as an index type
- sol2ts.py: Use discovery_dir as source_dir in single-file mode
  Fixes import paths being '../' instead of './' when processing single files

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Fix bytes32 cast and Constants reference in Yul assembly

- type_converter.py: Handle bytes32/bytesN casts of non-literal expressions
  Convert bigint to padded hex string at runtime: `0x${expr.toString(16).padStart(64, "0")}`
  Fixes TS2322: Type 'bigint' is not assignable to type 'string'

- yul.py: Prefix ALL_CAPS identifiers with Constants.
  Fixes TS2304: Cannot find name 'PACKED_CLEARED_MON_STATE'

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

* Use type registry for Yul constant resolution instead of heuristic

- YulTranspiler now accepts known_constants set from type registry
- StatementGenerator passes ctx.known_constants to YulTranspiler
- Replaces fragile ALL_CAPS heuristic with proper type tracking

https://claude.ai/code/session_01GjrjyxhRAhckrhyJGogaQw

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sudo-owen

transpiler/codegen/contract.py

@@ -402,12 +402,15 @@ def _generate_mapping_mutator(
             key_name = f'key{key_index}'
             key_params.append(f'{key_name}: {key_ts_type}')
 
+            # Convert non-string keys to string for Record indexing
+            key_access = key_name if key_ts_type == 'string' else f'String({key_name})'
+
             if current_type.value_type.is_mapping:
                 null_coalesce_lines.append(
-                    f'{body_indent}{access_path}[{key_name}] ??= {{}};'
+                    f'{body_indent}{access_path}[{key_access}] ??= {{}};'
                 )
 
-            access_path = f'{access_path}[{key_name}]'
+            access_path = f'{access_path}[{key_access}]'
             current_type = current_type.value_type
             key_index += 1
 

transpiler/codegen/statement.py

@@ -72,7 +72,7 @@ def __init__(
         super().__init__(ctx)
         self._expr = expr_generator
         self._type_converter = type_converter
-        self._yul_transpiler = YulTranspiler()
+        self._yul_transpiler = YulTranspiler(known_constants=ctx.known_constants)
 
     # =========================================================================
     # MAIN DISPATCH

transpiler/codegen/type_converter.py

@@ -190,15 +190,22 @@ def generate_type_cast(
             if expr != 'this' and not expr.startswith('"') and not expr.startswith("'"):
                 return f'{expr}._contractAddress'
 
-        # Handle bytes32 literals
+        # Handle bytes32 literals and expressions
         if type_name == 'bytes32':
             if isinstance(inner_expr, Literal) and inner_expr.kind in ('number', 'hex'):
                 return self._to_padded_bytes32(inner_expr.value)
+            # Non-literal: convert bigint to padded hex string at runtime
+            expr = generate_expression_fn(inner_expr)
+            return f'`0x${{{expr}.toString(16).padStart(64, "0")}}`'
 
         # Handle bytes types
         if type_name.startswith('bytes') and type_name != 'bytes':
             if isinstance(inner_expr, Literal) and inner_expr.kind in ('number', 'hex'):
                 return self._to_padded_bytes32(inner_expr.value)
+            # Non-literal: convert bigint to padded hex string at runtime
+            byte_size = int(type_name[5:]) if type_name[5:].isdigit() else 32
+            expr = generate_expression_fn(inner_expr)
+            return f'`0x${{{expr}.toString(16).padStart({byte_size * 2}, "0")}}`'
 
         # For numeric types (uint256, int128, etc.), just generate the inner expression
         # TypeScript's bigint handles the underlying value

transpiler/codegen/yul.py

@@ -48,6 +48,14 @@ class YulTranspiler:
     - mstore/mload → memory operations (usually no-op for simulation)
     """
 
+    def __init__(self, known_constants: set = None):
+        """Initialize with optional set of known constant names.
+
+        Args:
+            known_constants: Set of constant names that should be prefixed with 'Constants.'
+        """
+        self._known_constants = known_constants or set()
+
     def transpile(self, yul_code: str) -> str:
         """
         Transpile a Yul assembly block to TypeScript.
@@ -285,6 +293,10 @@ def _transpile_expr(self, expr: str, slot_vars: Dict[str, str]) -> str:
         if expr.isdigit():
             return f'{expr}n'
 
+        # Check if identifier is a known constant from type registry
+        if expr in self._known_constants:
+            return f'Constants.{expr}'
+
         # Return as-is (identifier)
         return expr
 

transpiler/sol2ts.py

@@ -13,7 +13,7 @@
 - Interface and contract inheritance
 
 Usage:
-    python -m transpiler src/
+    python transpiler/sol2ts.py src/
 
 This refactored version uses a modular architecture with separate packages for:
 - lexer: Tokenization (tokens.py, lexer.py)
@@ -244,6 +244,8 @@ def main():
     parser.add_argument('input', help='Input Solidity file or directory')
     parser.add_argument('-o', '--output', default='transpiler/ts-output', help='Output directory')
     parser.add_argument('--stdout', action='store_true', help='Print to stdout instead of file')
+    parser.add_argument('-d', '--discover', action='append', metavar='DIR',
+                        help='Directory to scan for type discovery')
     parser.add_argument('--stub', action='append', metavar='CONTRACT',
                         help='Contract name to generate as minimal stub')
     parser.add_argument('--emit-metadata', action='store_true',
@@ -254,12 +256,15 @@ def main():
     args = parser.parse_args()
 
     input_path = Path(args.input)
-    discovery_dirs = [str(input_path)] if input_path.is_dir() else [str(input_path.parent)]
+    discovery_dirs = args.discover or ([str(input_path)] if input_path.is_dir() else [str(input_path.parent)])
     stubbed_contracts = args.stub or []
     emit_metadata = args.emit_metadata or args.metadata_only
 
     if input_path.is_file():
+        # Use first discovery dir as source_dir for correct import path calculation
+        source_dir = discovery_dirs[0] if discovery_dirs else str(input_path.parent)
         transpiler = SolidityToTypeScriptTranspiler(
+            source_dir=source_dir,
             output_dir=args.output,
             discovery_dirs=discovery_dirs,
             stubbed_contracts=stubbed_contracts,