Sarthak Agarwal 3a092a28ba [WIP] Docs to JS/TS

2026-02-19 23:41:47 +05:30

15 KiB

Raw Blame History

Frictionless Setup Implementation Plan

Executive Summary

Transform Codeflash from a "config-required" tool to a "smart-defaults with optional config" tool, reducing setup friction while maintaining enterprise-grade configurability.

Key Principle: Use native config files only (pyproject.toml, package.json) - no new config formats.

Current State vs Target State

Aspect	Current State	Target State
First run	Error: "Run codeflash init"	Auto-detect → Quick confirm → Run
Config requirement	Mandatory for Python	Optional (smart defaults)
Setup questions	5-10 questions	1 confirmation (or 0 with `--yes`)
Config storage	pyproject.toml / package.json	Same - native files only
`codeflash init`	Required for all users	Optional - for GitHub Actions setup

User Flows

Flow 1: First-Time User (Zero Friction)

$ codeflash --file src/utils.py --function calculate

⚡ Welcome to Codeflash!

I auto-detected your project:
┌─────────────────────────────────────────┐
│ Language:     Python                    │
│ Module root:  src/                      │
│ Test runner:  pytest                    │
│ Formatter:    ruff (from pyproject.toml)│
│ Ignoring:     __pycache__, .venv, dist  │
└─────────────────────────────────────────┘

? Proceed with these settings? [Y/n/customize]
> Y

✅ Settings saved to codeflash.yaml
🔑 Enter API key: cf-xxxxx
✅ Running optimization...

Flow 2: Subsequent Runs (No Prompts)

$ codeflash --file src/utils.py --function calculate

⚡ Running optimization...

Flow 3: Enterprise Setup (`codeflash init`)

$ codeflash init

⚡ Codeflash Enterprise Setup

[Full wizard with all options]
[GitHub Actions integration]
[Team-wide config]

Flow 4: CI/CD (Config Required)

# In CI, config must exist - no interactive prompts
$ codeflash --all

# If no config: clear error with instructions

Architecture

New Components

codeflash/
├── setup/                          # NEW: Setup & detection module
│   ├── __init__.py
│   ├── detector.py                 # Universal auto-detection engine
│   ├── first_run.py                # First-run experience handler
│   ├── config_schema.py            # Universal config schema (Pydantic)
│   └── config_writer.py            # Write config to codeflash.yaml
│
├── code_utils/
│   ├── config_parser.py            # MODIFY: Add codeflash.yaml support
│   └── config_js.py                # KEEP: JS-specific detection
│
├── cli_cmds/
│   ├── cmd_init.py                 # MODIFY: Enterprise-focused
│   └── init_javascript.py          # DEPRECATE: Merge into setup/
│
└── main.py                         # MODIFY: Add first-run check

Config File Strategy (Native Files)

Use native config files for each language ecosystem:

Language	Config File	Section
Python	`pyproject.toml`	`[tool.codeflash]`
JavaScript	`package.json`	`{ "codeflash": {} }`
TypeScript	`package.json`	`{ "codeflash": {} }`
Rust (future)	`Cargo.toml`	`[package.metadata.codeflash]`
Go (future)	`codeflash.yaml`	Root level (Go has no standard)

Python Config (pyproject.toml)

[tool.codeflash]
module-root = "src"
tests-root = "tests"
ignore-paths = ["vendor/", "migrations/"]
formatter-cmds = ["ruff check --fix $file", "ruff format $file"]
# Optional
git-remote = "origin"
disable-telemetry = false
benchmarks-root = "benchmarks"

JavaScript/TypeScript Config (package.json)

{
  "codeflash": {
    "moduleRoot": "src",
    "ignorePaths": ["dist/", "coverage/"],
    "formatterCmds": ["npx prettier --write $file"]
  }
}

Why Native Files?

No extra file clutter - Uses existing config files
Ecosystem conventions - Developers expect config in standard locations
No tracking needed - Project root always has pyproject.toml or package.json
Tool discovery - Other tools already know where to look

Config Discovery Flow

find_project_and_config():
    1. Walk up from current directory
    2. Find project root (.git, package.json, pyproject.toml)
    3. Detect language from project root files
    4. Read codeflash config from appropriate native file
    5. If no codeflash section → first run experience

Implementation Phases

Phase 1: Universal Auto-Detection Engine

Goal: Create a single detection engine that works for all languages

Task 1.1: Create Detection Module Structure

Create codeflash/setup/ directory
Create codeflash/setup/__init__.py
Create codeflash/setup/detector.py

Task 1.2: Implement Universal Project Detector

File: codeflash/setup/detector.py

@dataclass
class DetectedProject:
    language: str                    # python | javascript | typescript
    project_root: Path
    module_root: Path
    tests_root: Path | None
    test_runner: str                 # pytest | jest | vitest | mocha
    formatter: list[str] | None
    ignore_paths: list[str]
    confidence: float                # 0.0 - 1.0

def detect_project(path: Path | None = None) -> DetectedProject:
    """Auto-detect all project settings."""
    ...

Task 1.3: Implement Language Detection

Detect from file extensions count
Detect from config files (pyproject.toml, package.json, tsconfig.json)
Detect from lockfiles (poetry.lock, yarn.lock, etc.)
Return confidence score

Task 1.4: Implement Module Root Detection

Python: Look for __init__.py, src/ convention, pyproject.toml name
JS/TS: Look for package.json exports/main, src/ convention
Generic: Find directory with most source files

Task 1.5: Implement Tests Root Detection

Look for tests/, test/, tests/ directories
Look for *_test.py, *.test.js patterns
Check pytest.ini, jest.config.js locations

Task 1.6: Implement Test Runner Detection

Python: Check for pytest, unittest in dependencies/config
JS/TS: Check for jest, vitest, mocha in devDependencies
Parse test scripts in package.json

Task 1.7: Implement Formatter Detection

Python: Check ruff.toml, pyproject.toml [tool.ruff], black config
JS/TS: Check .prettierrc, .eslintrc, devDependencies
Return formatter commands list

Task 1.8: Implement Ignore Paths Detection

Parse .gitignore
Add language-specific defaults (node_modules, pycache, etc.)
Merge with any existing config

Phase 2: Universal Config Schema

Goal: Single config format that works for all languages

Task 2.1: Create Config Schema

File: codeflash/setup/config_schema.py

from pydantic import BaseModel

class CodeflashConfig(BaseModel):
    version: int = 1
    language: str
    module_root: str
    tests_root: str | None = None
    ignore_paths: list[str] = []
    formatter_commands: list[str] = []
    test_runner: str | None = None
    git_remote: str = "origin"
    disable_telemetry: bool = False
    benchmarks_root: str | None = None

Task 2.2: Create Config Writer

File: codeflash/setup/config_writer.py

Write to codeflash.yaml (primary)
Optionally write to pyproject.toml (Python projects)
Optionally write to package.json (JS/TS projects)

Task 2.3: Update Config Parser

File: codeflash/code_utils/config_parser.py

Add codeflash.yaml as primary config source
Maintain backward compatibility with pyproject.toml
Maintain backward compatibility with package.json
Priority: codeflash.yaml > pyproject.toml > package.json

Task 2.4: Create Config Finder

find_config_file() - Search for any valid config
Walk up directory tree to find project root
Return config file path and type

Phase 3: First-Run Experience

Goal: Seamless first-run with auto-detection and quick confirm

Task 3.1: Create First-Run Handler

File: codeflash/setup/first_run.py

def is_first_run() -> bool:
    """Check if this is first run (no config exists)."""
    ...

def handle_first_run(args: Namespace) -> Namespace:
    """Handle first-run experience with auto-detection."""
    ...

Task 3.2: Implement First-Run Detection

Check for codeflash.yaml in project root
Check for [tool.codeflash] in pyproject.toml
Check for codeflash section in package.json
Return True if none found

Task 3.3: Implement First-Run UI

Show welcome message
Display auto-detected settings in table
Quick confirm prompt: Y/n/customize
Handle --yes flag to skip prompt

Task 3.4: Implement API Key Prompt (First Run Only)

Check for CODEFLASH_API_KEY env var
If missing, prompt for API key
Offer OAuth login option
Save to shell rc file

Task 3.5: Implement Config Auto-Save

After confirmation, save config to codeflash.yaml
Show saved location
Continue with optimization

Task 3.6: Integrate with Main Entry Point

File: codeflash/main.py

Check is_first_run() before loading config
If first run, call handle_first_run()
If not first run, proceed normally

Phase 4: Refactor `codeflash init` for Enterprise

Goal: Make init command focused on enterprise/CI setup

Task 4.1: Simplify Init Command

File: codeflash/cli_cmds/cmd_init.py

Remove redundant questions (auto-detect instead)
Focus on: API key, GitHub Actions, advanced overrides
Add --enterprise flag for full wizard

Task 4.2: Create Enterprise Wizard

All current questions available
Team-wide config options
GitHub Actions setup
CI/CD validation mode

Task 4.3: Merge JS/TS Init into Main Init

Remove init_javascript.py as separate module
Use universal detector for all languages
Same flow regardless of language

Task 4.4: Update Help Text

codeflash init - Quick setup with auto-detection
codeflash init --enterprise - Full enterprise wizard
Document that init is optional for most users

Phase 5: CLI Updates

Goal: Support new flow with appropriate flags

Task 5.1: Add New CLI Flags

File: codeflash/cli_cmds/cli.py

# New flags
--yes, -y           # Skip confirmation prompts
--no-save           # Don't save config (one-off run)
--show-config       # Show detected/current config and exit
--reset-config      # Delete saved config, re-detect

Task 5.2: Update Main Entry Point