# networkXR Agent Guidelines

## Project Overview
networkXR is a high-performance, Rust-accelerated drop-in replacement for NetworkX. It uses:
- **Rust** (via PyO3 + maturin) for core graph data structures and algorithms.
- **Python** (3.12+) for the public API surface, compatibility shims, and graph views.
- **uv** for Python package management and virtual environment execution.
- **IndexMap** for deterministic insertion-ordered node/edge storage in Rust.

## Critical Rules

### Always Use `uv`
- **All Python commands MUST use `uv run`** — never use `.venv/bin/python` or bare `python`.
- Tests: `uv run pytest tests/ -x -q`
- Benchmarks: `uv run pytest tests/test_benchmarks.py --benchmark-only`
- Type checking: `uv run pyright`
- Smoke test: `uv run python -c "import networkxr; print(networkxr.__version__)"`

### Build Workflow
1. `cargo check` — fast compilation check for the Rust codebase.
2. `uv run maturin develop --release` — build optimized extension and inject it into the `.venv`.

### Pre-Commit Checklist
1. `cargo check` — no Rust errors.
2. `uv run maturin develop --release` — build extension.
3. `uv run pytest tests/ -x -q` — all tests pass (always run tests before commit).
4. `uv run pyright` — type checking passes.
*(Run benchmarks after implementing new features)*

### General Development Guidelines
- **File Size Limit**: No file should exceed 1000 lines of code.
- **Branching**: This project operates **exclusively on the `main` branch**. Do not create feature branches under any circumstances. All commits and pushes must go directly to `main`.
- **Temporary / scratch files**: Never drop throwaway files in the repo root or anywhere tracked by git. Use `.temp/` if needed.

## YOLO (Main-Branch Workflow)

This project works directly on **`main`** — there is no PR/branch review step. **YOLO** means: `git add -A && git commit && git push origin main` **and** release a new version — all in one go.

Steps:
1. `git add -A`
2. `git commit -m "<message>"`
3. Bump version in `Cargo.toml` and `pyproject.toml`, then `git commit -am "release: vX.Y.Z"`
4. `git tag vX.Y.Z`
5. `git push origin main && git push origin vX.Y.Z`

CI takes it from there. 🚀

## Releasing a New Version

The CI automatically builds wheels for all platforms and publishes to PyPI when a **git tag** is pushed.

### Steps
1. **Bump version** in both `Cargo.toml` (under `[package]`) and `pyproject.toml` (under `[project]`).
2. **Commit** the version bump: `git commit -am "release: v0.X.Y"`
3. **Tag** the commit: `git tag v0.X.Y`
4. **Push** the tag: `git push origin main && git push origin v0.X.Y`
5. CI will:
   - Run tests on Python 3.12–3.13 (ubuntu + macos).
   - Build wheels for linux (x86_64, aarch64), macos (universal2), and windows (x64).
   - Publish to PyPI.
   - Create a GitHub Release with auto-generated release notes.

### Commit Convention
Use [Conventional Commits](https://www.conventionalcommits.org/) for automatic changelog categorization:

| Prefix | Category | Example |
|--------|----------|---------|
| `feat:` | 🚀 Features | `feat: add MultiDiGraph support` |
| `fix:` | 🐛 Bug Fixes | `fix: handle self-loops in degree calculation` |
| `perf:` | ⚡ Performance | `perf: zero-copy node iteration via Rust` |
| `refactor:` | 🔧 Refactoring | `refactor: split graph views into separate module` |
| `docs:` | 📖 Documentation | `docs: add DiGraph API reference` |
| `ci:` | 🔄 CI/CD | `ci: add windows wheel target` |
| `chore:` | 📦 Miscellaneous | `chore: update pyo3 to 0.28` |
| `release:` | _(skipped)_ | `release: v0.1.1` |

The changelog is generated by `git-cliff` using `cliff.toml` config.

### Generate Changelog Locally
```bash
# Install git-cliff
cargo install git-cliff

# Preview changelog for unreleased changes
git cliff --unreleased

# Full changelog
git cliff
```

### Verify before releasing
```bash
cargo check
uv run maturin develop --release
uv run pytest tests/ -x -q
uv run pyright
```

## Architecture & API

networkXR mirrors the NetworkX API while accelerating core operations in Rust.

### Graph Classes

```
Graph         — Undirected graph (Rust-backed via _networkxr.RustGraph)
DiGraph       — Directed graph (Rust-backed via _networkxr.RustDiGraph)
MultiGraph    — Undirected multigraph (pure Python, planned Rust acceleration)
```

### Module Layout

| Module | Purpose |
|--------|---------|
| `networkxr/classes/graph.py` | `Graph` class (wraps Rust `RustGraph`) |
| `networkxr/classes/digraph.py` | `DiGraph` class (wraps Rust `RustDiGraph`) |
| `networkxr/multigraph.py` | `MultiGraph` class (pure Python) |
| `networkxr/convert.py` | Converters (dict-of-dicts, edge lists, adjacency) |
| `networkxr/generators/` | Graph generators (classic, small, random) |
| `networkxr/relabel.py` | Node relabeling utilities |
| `networkxr/exception.py` | NetworkX-compatible exceptions |
| `networkxr/utils/` | Decorators, union-find, miscellaneous utilities |
| `src/graph.rs` | Rust `RustGraph` implementation |
| `src/digraph.rs` | Rust `RustDiGraph` implementation |
| `src/views.rs` | Rust view objects (NodeView, EdgeView, AdjacencyView) |
| `src/lib.rs` | PyO3 module registration |

### Design Principles
- **Drop-in compatibility**: `import networkxr as nx` should work as a NetworkX replacement.
- **Rust acceleration**: Core graph operations (add/remove nodes/edges, adjacency queries, iteration) are implemented in Rust for performance.
- **Python views**: NodeView, EdgeView, DegreeView wrap Rust iterators and support the full NetworkX view API.
- **Type stubs**: `.pyi` files provide full type information for IDE support (`_networkxr.pyi`, `__init__.pyi`, etc.).

## CI/CD Workflows (`.github/workflows/`)

### `ci.yml` — Lint & Test
- **Triggers**: push to `main`, PRs to `main`.
- **Rust checks**: `cargo fmt --check` + `cargo clippy`.
- **Test matrix**: Python 3.12–3.13 on ubuntu + macos.
- **Steps**: `uv sync --dev` → `maturin develop --release` → `pytest`.

### `release.yml` — Build Wheels & Publish
- **Triggers**: tag push (`v*`).
- **Builds**: sdist + wheels for linux (x86_64, aarch64), macos (universal2), windows (x64).
- **Publishes** to PyPI via trusted publishing.
- **Creates** a GitHub Release with wheel assets.

### Important CI/CD Rules
- **Never commit `site/`** — it's the Zensical build output and is in `.gitignore`.
- **All repo references must use `bmsuisse/networkXR`**.
- **Action versions**: keep `actions/checkout`, `actions/setup-python`, `astral-sh/setup-uv` in sync across both workflows.
- **uv consistency**: always use `uv run` — never `uv pip install --system`.

## Documentation

Documentation is built with **Zensical** (configured in `zensical.toml`).

| Command | Purpose |
|---------|---------|
| `uv run zensical serve` | Preview docs locally |
| `uv run zensical build` | Build static site into `site/` |
| `uv run python scripts/gen_api_reference.py` | Regenerate API reference docs |
| `uv run python scripts/sync_changelog.py` | Sync changelog from git-cliff |
