Merge branch 'main' into feat/behavior-test-as-tool

Author: aseembits93

.claude/rules/architecture.md

@@ -0,0 +1,42 @@
+# Architecture
+
+```
+codeflash/
+├── main.py                 # CLI entry point
+├── cli_cmds/               # Command handling, console output (Rich)
+├── discovery/              # Find optimizable functions
+├── context/                # Extract code dependencies and imports
+├── optimization/           # Generate optimized code via AI
+│   ├── optimizer.py        # Main optimization orchestration
+│   └── function_optimizer.py  # Per-function optimization logic
+├── 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)
+├── setup/                  # Config schema, auto-detection, first-run experience
+├── picklepatch/            # Serialization/deserialization utilities
+├── tracing/                # Function call tracing
+├── tracer.py               # Root-level tracer entry point for profiling
+├── lsp/                    # IDE integration (Language Server Protocol)
+├── telemetry/              # Sentry, PostHog
+├── either.py               # Functional Result type for error handling
+├── result/                 # Result types and handling
+└── version.py              # Version information
+```
+
+## Key Entry Points
+
+| Task | Start here |
+|------|------------|
+| CLI arguments & commands | `cli_cmds/cli.py` |
+| Optimization orchestration | `optimization/optimizer.py` → `run()` |
+| Per-function optimization | `optimization/function_optimizer.py` |
+| Function discovery | `discovery/functions_to_optimize.py` |
+| Context extraction | `context/code_context_extractor.py` |
+| Test execution | `verification/test_runner.py`, `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`) |

.claude/rules/code-style.md

@@ -0,0 +1,10 @@
+# Code Style
+
+- **Line length**: 120 characters
+- **Python**: 3.9+ syntax
+- **Package management**: Always use `uv`, never `pip`
+- **Tooling**: Ruff for linting/formatting, mypy strict mode, prek for pre-commit checks
+- **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)

.claude/rules/git.md

@@ -0,0 +1,7 @@
+# Git Commits & Pull Requests
+
+- **Always create a new branch from `main` before starting any new work** — never commit directly to `main` or reuse an existing feature branch for unrelated changes
+- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
+- Keep commits atomic - one logical change per commit
+- Commit message body should be concise (1-2 sentences max)
+- PR titles should also use conventional format

.claude/rules/language-patterns.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "codeflash/languages/**/*.py"
+---
+
+# Language Support Patterns
+
+- Current language is a module-level singleton in `languages/current.py` — use `set_current_language()` / `current_language()`, never pass language as a parameter through call chains
+- 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

.claude/rules/optimization-patterns.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "codeflash/optimization/**/*.py"
+  - "codeflash/verification/**/*.py"
+  - "codeflash/benchmarking/**/*.py"
+  - "codeflash/context/**/*.py"
+---
+
+# Optimization Pipeline Patterns
+
+- All major operations return `Result[SuccessType, ErrorType]` — construct with `Success(value)` / `Failure(error)`, check with `is_successful()` before calling `unwrap()`
+- Code context has token limits (`OPTIMIZATION_CONTEXT_TOKEN_LIMIT`, `TESTGEN_CONTEXT_TOKEN_LIMIT` in `config_consts.py`) — exceeding them rejects the function
+- `read_writable_code` can span multiple files; `read_only_context_code` is reference-only
+- Code is serialized as markdown code blocks: ` ```language:filepath\ncode\n``` ` (see `CodeStringsMarkdown`)
+- Candidates form a forest (DAG): refinements/repairs reference `parent_id` on previous candidates
+- Test generation and optimization run concurrently — coordinate through `CandidateEvaluationContext`
+- Generated tests are instrumented with `codeflash_capture.py` to record return values and traces

.claude/rules/source-code.md

@@ -0,0 +1,8 @@
+---
+paths:
+  - "codeflash/**/*.py"
+---
+
+# Source Code Rules
+
+- Use `libcst` for code modification/transformation to preserve formatting. `ast` is acceptable for read-only analysis and parsing.

.claude/rules/testing.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "tests/**"
+  - "codeflash/**/*test*.py"
+---
+
+# Testing Conventions
+
+- Code context extraction and replacement tests must always assert for full string equality, no substring matching.
+- Use pytest's `tmp_path` fixture for temp directories (it's a `Path` object).
+- Write temp files inside `tmp_path`, never use `NamedTemporaryFile` (causes Windows file contention).
+- Always call `.resolve()` on Path objects to ensure absolute paths and resolve symlinks.
+- Use `.as_posix()` when converting resolved paths to strings (normalizes to forward slashes).
+- Any new feature or bug fix that can be tested automatically must have test cases.
+- If changes affect existing test expectations, update the tests accordingly. Tests must always pass after changes.
+- The pytest plugin patches `time`, `random`, `uuid`, and `datetime` for deterministic test execution — never assume real randomness or real time in verification tests.
+- `conftest.py` uses an autouse fixture that calls `reset_current_language()` — tests always start with Python as the default language.

.claude/skills/fix-mypy.md

@@ -0,0 +1,12 @@
+# Fix mypy errors
+
+When modifying code, fix any mypy type errors in the files you changed:
+
+```bash
+uv run mypy --non-interactive --config-file pyproject.toml <changed_files>
+```
+
+- Fix type annotation issues: missing return types, incorrect types, Optional/None unions, import errors for type hints
+- Do NOT add `# type: ignore` comments — always fix the root cause
+- Do NOT fix type errors that require logic changes, complex generic type rework, or anything that could change runtime behavior
+- Files in `mypy_allowlist.txt` are checked in CI — ensure they remain error-free

.claude/skills/fix-prek.md

@@ -0,0 +1,9 @@
+# Fix prek failures
+
+When prek (pre-commit) checks fail:
+
+1. Run `uv run prek run` to see failures (local, checks staged files)
+2. In CI, the equivalent is `uv run prek run --from-ref origin/main`
+3. prek runs ruff format, ruff check, and mypy on changed files
+4. Fix issues in order: formatting → lint → type errors
+5. Re-run `uv run prek run` to verify all checks pass

.codex/skills/.gitignore

@@ -0,0 +1,2 @@
+# Managed by Tessl
+tessl:*