Merge branch 'main' of github.com:codeflash-ai/codeflash

Author: mohammedahmed18

.claude/rules/architecture.md

@@ -26,3 +26,17 @@ codeflash/
 ├── 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

@@ -2,6 +2,7 @@
 
 - **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

.claude/rules/git.md

@@ -1,5 +1,6 @@
 # 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)

.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

@@ -6,6 +6,3 @@ paths:
 # Source Code Rules
 
 - Use `libcst` for code modification/transformation to preserve formatting. `ast` is acceptable for read-only analysis and parsing.
-- NEVER use leading underscores for function names (e.g., `_helper`). Python has no true private functions. Always use public names.
-- 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.

.claude/rules/testing.md

@@ -13,3 +13,5 @@ paths:
 - 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:*