69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
CoinHunter is a Python CLI package using a `src/` layout. Application code lives in `src/coinhunter/`.
|
|
|
|
- `src/coinhunter/cli.py` defines CLI parsing and command dispatch for `coinhunter` and `coin`.
|
|
- `src/coinhunter/binance/` contains thin Binance Spot client wrappers.
|
|
- `src/coinhunter/services/` contains domain logic for account, market, trade, portfolio, opportunity, dataset, research, and evaluation flows.
|
|
- `src/coinhunter/config.py`, `runtime.py`, and `audit.py` handle runtime config, output, completions, upgrade flow, and logs.
|
|
- `tests/` contains pytest/unittest coverage by service area.
|
|
- `dist/` contains built release artifacts; do not edit these manually.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Install locally with development tools:
|
|
|
|
```bash
|
|
python -m pip install -e '.[dev]'
|
|
```
|
|
|
|
Run the CLI from the working tree:
|
|
|
|
```bash
|
|
coinhunter --help
|
|
coin opportunity -s BTCUSDT ETHUSDT --agent
|
|
```
|
|
|
|
Quality checks:
|
|
|
|
```bash
|
|
pytest tests/ # run the full test suite
|
|
ruff check src tests # lint and import ordering
|
|
mypy src # static type checks
|
|
```
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use Python 3.10+ syntax and 4-space indentation. Keep modules small and service-oriented; prefer adding logic under `src/coinhunter/services/` and keeping `cli.py` focused on argument parsing and dispatch.
|
|
|
|
Use `snake_case` for functions, variables, and modules. Use `PascalCase` for classes and dataclasses. Preserve existing payload key naming conventions such as `notional_usdt`, `quote_volume`, and `opportunity_score`.
|
|
|
|
Ruff enforces `E`, `F`, `I`, `W`, `UP`, `B`, `C4`, and `SIM`; line length `E501` is ignored.
|
|
|
|
## Testing Guidelines
|
|
|
|
Tests use `pytest` with `unittest.TestCase`. Add tests near the changed behavior:
|
|
|
|
- CLI dispatch: `tests/test_cli.py`
|
|
- Config/runtime: `tests/test_config_runtime.py`
|
|
- Opportunity logic: `tests/test_opportunity_service.py`
|
|
- Dataset/evaluation flows: `tests/test_opportunity_dataset_service.py`
|
|
|
|
Name tests as `test_<behavior>`. Prefer fake clients and injected HTTP functions over live network calls. Run `pytest tests/` before submitting changes.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Recent history uses short imperative subjects, often Conventional Commit prefixes:
|
|
|
|
- `feat: configurable ticker window for market stats`
|
|
- `fix: use rolling_window_ticker for symbol-specific queries`
|
|
- `refactor: flatten account command to a single balances view`
|
|
|
|
Keep commits focused and describe user-visible behavior. Pull requests should include a concise summary, validation commands run, and any config or CLI changes. Link issues when applicable. For CLI output changes, include before/after examples or JSON snippets.
|
|
|
|
## Security & Configuration Tips
|
|
|
|
Never commit Binance API keys, secrets, runtime logs, or local `~/.coinhunter` files. Runtime secrets belong in `~/.coinhunter/.env`; configuration belongs in `~/.coinhunter/config.toml`. Use `COINHUNTER_HOME` for isolated test runs.
|