Metadata-Version: 2.4
Name: churn-cli
Version: 0.3.0
Summary: Read your codebase. Generate interview questions or full project docs.
Author: dhawalshankar
Project-URL: Homepage, https://github.com/DhawalShankar/project-churn
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: google-genai
Requires-Dist: click
Requires-Dist: python-dotenv
Requires-Dist: questionary
Requires-Dist: markdown
Provides-Extra: pdf
Requires-Dist: xhtml2pdf; extra == "pdf"

# Churn
> One command. Every doc your project needs. Every question your interview demands.

---

## Install

```bash
pip install churn-cli
```

For PDF export support (`--only pdf`):

```bash
pip install "churn-cli[pdf]"
```

Requires Python 3.8+ and a Gemini API key from [aistudio.google.com](https://aistudio.google.com)

---

## Usage

Churn has two commands: `interview` for interview prep, and `docs` for documentation generation.

```bash
churn interview /path/to/your/project
churn docs /path/to/your/project
```

First run pe Gemini API key maangega — ek baar enter karo, save ho jaata hai globally.

---

## `churn interview`

Generates level-wise interview Q&A from your codebase.

```bash
churn interview /path/to/project
churn interview /path/to/project --level senior          # skip interactive prompt
churn interview /path/to/project --questions 15           # custom question count (default: 10)
churn interview /path/to/project --output report.md        # custom output file
churn interview /path/to/project --format json             # json output instead of markdown
churn interview /path/to/project --ignore tests/ --ignore migrations/   # skip folders
```

### Options

```
-q, --questions INTEGER           Number of questions  [default: 10]
-l, --level [fresher|mid|senior]  Skip prompt, set level directly
-o, --output TEXT                 Output file  [default: churn-output.md]
-f, --format [md|json]            Output format  [default: md]
-i, --ignore TEXT                 Extra folders to ignore (repeatable)
```

### Output Example

```markdown
# Churn — MID Level

**Q1: In `matchingService.js`, what are the three criteria for a perfect match?**

The `findMatches` function checks: same campus, userProfile's wantedElectives includes
student's currentElective, and student's wantedElectives includes userProfile's currentElective.

---
```

---

## `churn docs`

Generates complete project documentation from your codebase.

```bash
churn docs /path/to/project
churn docs /path/to/project --only readme,prd          # generate only specific docs
churn docs /path/to/project --only readme,prd,arch,pdf # include a combined PDF report
churn docs /path/to/project --output my-docs/           # custom output folder
churn docs /path/to/project --ignore tests/             # skip folders
```

### Options

```
--only TEXT        Comma separated: readme, prd, arch, pdf  [default: readme,prd,arch]
-o, --output TEXT  Output folder  [default: churn-docs/]
-i, --ignore TEXT  Extra folders to ignore (repeatable)
```

### Output

```
churn-docs/
├── README.md       — what it does, setup, usage, tech stack
├── PRD.md          — problem, features, roadmap inferred from code
├── ARCHITECTURE.md — folder structure, data flow, key files
└── REPORT.pdf       — all three combined, shareable (only with --only ...,pdf)
```

Each doc is generated strictly from what's in the code — README, PRD, and ARCHITECTURE
don't invent features, flags, or files that aren't actually there. The PRD's roadmap
section is inferred from real TODOs and unfinished code paths, not guesses.

> PDF export uses `xhtml2pdf` (pure Python) — no native GTK/Cairo dependencies, so it
> works out of the box on Windows, macOS, and Linux. Requires `pip install "churn-cli[pdf]"`.

---

## Global Flags

```bash
churn --version   # show version
churn --help      # show all options
```

---

## What It Does

Churn scans a local project directory, identifies the most frequently edited files using `git log`, compresses the code, and sends it to the Gemini API.

- `churn interview` returns interview questions with detailed answers, saved as markdown or JSON.
- `churn docs` returns a full documentation set (README, PRD, ARCHITECTURE, and an optional combined PDF report).

---

## Files Scanned

**Included:** `.py` `.js` `.ts` `.tsx` `.jsx` `.java` `.go` `.cpp` `.env.example`

**Ignored:** `node_modules/` `.git/` `dist/` `build/` `__pycache__/` `.next/` `venv/` `churn-env/`

---

## Privacy

- No code is stored at any point
- Everything runs locally — no backend server
- Code is sent to Gemini API for processing only
- Gemini API does not use API request data for model training

---

## Tech Stack

- Python 3.8+
- `google-genai` — Gemini API SDK
- `click` — CLI
- `python-dotenv` — environment variables
- `questionary` — interactive prompts
- `markdown` + `xhtml2pdf` — PDF report export (optional)

---

## Local Development

```bash
git clone https://github.com/DhawalShankar/project-churn
cd project-churn
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # Mac/Linux
pip install -e ".[pdf]"
churn interview /path/to/project
churn docs /path/to/project
```

---

## Roadmap

- [x] PyPI publish — `pip install churn-cli`
- [x] Custom question count — `--questions`
- [x] Custom output path — `--output`
- [x] JSON export — `--format json`
- [x] Skip folders — `--ignore`
- [x] `churn docs` — README, PRD, ARCHITECTURE generation
- [x] PDF export — `REPORT.pdf`
- [ ] Multi-provider support (Groq, OpenAI, Claude) — `--provider`
- [ ] GitHub public repo URL support
- [ ] VS Code Extension
- [ ] Custom focus flag — `--focus security`

---

## License

Personal project. All rights reserved.
© 2026 dhawalshankar
