Merge branch 'main' into chore/docstring-updates

Author: aseembits93

.claude/rules/architecture.md

@@ -1,20 +1,45 @@
 # Architecture
 
+When adding, moving, or deleting source files, update this doc to match.
+
 ```
 codeflash/
 ├── main.py                 # CLI entry point
 ├── cli_cmds/               # Command handling, console output (Rich)
+│   ├── cmd_init.py         # Init orchestrator + Python-specific setup
+│   ├── init_config.py      # Config types, validation, writing, shared UI helpers
+│   ├── init_auth.py        # API key management + GitHub app installation
+│   ├── github_workflow.py  # GitHub Actions workflow generation
+│   ├── init_javascript.py  # JavaScript/TypeScript project initialization
+│   └── oauth_handler.py    # OAuth PKCE flow for CodeFlash authentication
 ├── discovery/              # Find optimizable functions
 ├── optimization/           # Generate optimized code via AI
-│   ├── optimizer.py        # Main optimization orchestration
-│   └── function_optimizer.py  # Per-function optimization logic
+│   └── optimizer.py        # Main optimization orchestration
 ├── verification/           # Run deterministic tests (pytest plugin)
 ├── benchmarking/           # Performance measurement
 ├── github/                 # PR creation
 ├── api/                    # AI service communication
 ├── code_utils/             # Code parsing, git utilities
 ├── models/                 # Pydantic models and types
-├── languages/              # Multi-language support (Python, JavaScript/TypeScript)
+├── languages/              # Multi-language support (Python, JavaScript/TypeScript, Java planned)
+│   ├── base.py                    # LanguageSupport protocol and shared data types
+│   ├── registry.py                # Language registration and lookup by extension/enum
+│   ├── current.py                 # Current language singleton (set_current_language / current_language_support)
+│   ├── function_optimizer.py       # FunctionOptimizer base class for per-function optimization
+│   ├── code_replacer.py           # Language-agnostic code replacement
+│   ├── python/
+│   │   ├── support.py             # PythonSupport (LanguageSupport implementation)
+│   │   ├── function_optimizer.py  # PythonFunctionOptimizer subclass
+│   │   ├── optimizer.py           # Python module preparation & AST resolution
+│   │   ├── normalizer.py          # Python code normalization for deduplication
+│   │   ├── test_runner.py         # Test subprocess execution for Python
+│   │   ├── instrument_codeflash_capture.py  # Instrument __init__ with capture decorators
+│   │   └── parse_line_profile_test_output.py  # Parse line profiler output
+│   └── javascript/
+│       ├── support.py             # JavaScriptSupport (LanguageSupport implementation)
+│       ├── function_optimizer.py  # JavaScriptFunctionOptimizer subclass
+│       ├── optimizer.py           # JS project root finding & module preparation
+│       └── normalizer.py          # JS/TS code normalization for deduplication
 ├── setup/                  # Config schema, auto-detection, first-run experience
 ├── picklepatch/            # Serialization/deserialization utilities
 ├── tracing/                # Function call tracing
@@ -30,12 +55,38 @@ codeflash/
 
 | Task | Start here |
 |------|------------|
-| CLI arguments & commands | `cli_cmds/cli.py` |
+| CLI arguments & commands | `cli_cmds/cli.py` (parsing), `main.py` (subcommand dispatch) |
 | Optimization orchestration | `optimization/optimizer.py` → `run()` |
-| Per-function optimization | `optimization/function_optimizer.py` |
+| Per-function optimization | `languages/function_optimizer.py` (base), `languages/python/function_optimizer.py`, `languages/javascript/function_optimizer.py` |
 | Function discovery | `discovery/functions_to_optimize.py` |
 | Context extraction | `languages/<lang>/context/code_context_extractor.py` |
-| Test execution | `verification/test_runner.py`, `verification/pytest_plugin.py` |
+| Test execution | `languages/<lang>/support.py` (`run_behavioral_tests`, etc.), `verification/pytest_plugin.py` |
 | Performance ranking | `benchmarking/function_ranker.py` |
 | Domain types | `models/models.py`, `models/function_types.py` |
 | Result handling | `either.py` (`Result`, `Success`, `Failure`, `is_successful`) |
+
+## LanguageSupport Protocol Methods
+
+Core protocol in `languages/base.py`. Each language (`PythonSupport`, `JavaScriptSupport`) implements these.
+
+| Category | Method/Property | Purpose |
+|----------|----------------|---------|
+| Identity | `language`, `file_extensions`, `default_file_extension` | Language identification |
+| Identity | `comment_prefix`, `dir_excludes` | Language conventions |
+| AI service | `default_language_version` | Language version for API payloads (`None` for Python, `"ES2022"` for JS) |
+| AI service | `valid_test_frameworks` | Allowed test frameworks for validation |
+| Discovery | `discover_functions`, `discover_tests` | Find optimizable functions and their tests |
+| Discovery | `adjust_test_config_for_discovery` | Pre-discovery config adjustment (no-op default) |
+| Context | `extract_code_context`, `find_helper_functions`, `find_references` | Code dependency extraction |
+| Transform | `replace_function`, `format_code`, `normalize_code` | Code modification |
+| Validation | `validate_syntax` | Syntax checking |
+| Test execution | `run_behavioral_tests`, `run_benchmarking_tests`, `run_line_profile_tests` | Test runners |
+| Test results | `test_result_serialization_format` | `"pickle"` (Python) or `"json"` (JS) |
+| Test results | `load_coverage` | Load coverage from language-specific format |
+| Test results | `compare_test_results` | Equivalence checking between original and candidate |
+| Test gen | `postprocess_generated_tests` | Post-process `GeneratedTestsList` objects |
+| Test gen | `process_generated_test_strings` | Instrument/transform raw generated test strings |
+| Module | `detect_module_system` | Detect project module system (`None` for Python, `"esm"`/`"commonjs"` for JS) |
+| Module | `prepare_module` | Parse/validate module before optimization |
+| Setup | `setup_test_config` | One-time project setup after language detection |
+| Optimizer | `function_optimizer_class` | Return `FunctionOptimizer` subclass for this language |

.claude/rules/code-style.md

@@ -7,4 +7,7 @@
 - **Comments**: Minimal - only explain "why", not "what"
 - **Docstrings**: Do not add unless explicitly requested
 - **Naming**: NEVER use leading underscores (`_function_name`) - Python has no true private functions, use public names
-- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
+- **Paths**: Always use absolute paths
+- **Encoding**: Always pass `encoding="utf-8"` to `open()`, `read_text()`, `write_text()`, etc. in new or changed code — Windows defaults to `cp1252` which breaks on non-ASCII content. Don't flag pre-existing code that lacks it unless you're already modifying that line.
+- **Pre-commit**: Run `uv run prek` before committing — fix any issues before creating the commit
+- **Pre-push**: Before pushing, run `uv run prek run --from-ref origin/<base>` to check all changed files against the PR base — this matches CI behavior and catches issues that per-commit prek misses. To detect the base branch: `gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main`

.claude/rules/language-patterns.md

@@ -9,4 +9,5 @@ paths:
 - Use `get_language_support(identifier)` from `languages/registry.py` to get a `LanguageSupport` instance — never import language classes directly
 - New language support classes must use the `@register_language` decorator to register with the extension and language registries
 - `languages/__init__.py` uses `__getattr__` for lazy imports to avoid circular dependencies — follow this pattern when adding new exports
-- `is_javascript()` returns `True` for both JavaScript and TypeScript
+- Prefer `LanguageSupport` protocol dispatch over `is_python()`/`is_javascript()` guards — remaining guards are being migrated to protocol methods
+- `is_javascript()` returns `True` for both JavaScript and TypeScript (still used in ~15 call sites pending migration)

.claude/rules/optimization-patterns.md

@@ -3,7 +3,7 @@ paths:
   - "codeflash/optimization/**/*.py"
   - "codeflash/verification/**/*.py"
   - "codeflash/benchmarking/**/*.py"
-  - "codeflash/context/**/*.py"
+  - "codeflash/languages/*/context/**/*.py"
 ---
 
 # Optimization Pipeline Patterns