|
| 1 | +<!-- OPENSPEC:START --> |
| 2 | +# OpenSpec Instructions |
| 3 | + |
| 4 | +These instructions are for AI assistants working in this project. |
| 5 | + |
| 6 | +Always open `@/openspec/AGENTS.md` when the request: |
| 7 | +- Mentions planning or proposals (words like proposal, spec, change, plan) |
| 8 | +- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work |
| 9 | +- Sounds ambiguous and you need the authoritative spec before coding |
| 10 | + |
| 11 | +Use `@/openspec/AGENTS.md` to learn: |
| 12 | +- How to create and apply change proposals |
| 13 | +- Spec format and conventions |
| 14 | +- Project structure and guidelines |
| 15 | + |
| 16 | +Keep this managed block so 'openspec update' can refresh the instructions. |
| 17 | + |
| 18 | +<!-- OPENSPEC:END --> |
| 19 | + |
| 20 | +# Repository Guidelines |
| 21 | + |
| 22 | +## Project Structure & Module Organization |
| 23 | +- Workspace: Rust 2021, crates in `sequila/`. |
| 24 | +- Core library: `sequila/sequila-core` — DataFusion extensions, physical planner, and interval-join optimization. |
| 25 | +- CLI: `sequila/sequila-cli` — REPL and file execution for SQL. |
| 26 | +- Tests: unit/integration under `sequila/sequila-core/tests` and crate-local tests; benches in `sequila/sequila-core/benches`. |
| 27 | +- Utilities/data: `queries/` for sample SQL, `testing/data/` for local datasets, `bin/env.sh` for env helpers. |
| 28 | + |
| 29 | +## Build, Test, and Development Commands |
| 30 | +- Build: `cargo build` (release: `cargo build --release`). |
| 31 | +- Run CLI: `RUST_LOG=info cargo run -p sequila-cli -- --file queries/q1-coitrees.sql`. |
| 32 | +- REPL: `RUST_LOG=info cargo run -p sequila-cli`. |
| 33 | +- Tests: `cargo test --workspace` (async tests use Tokio). |
| 34 | +- Benchmarks: `RUSTFLAGS="-Ctarget-cpu=native" cargo bench --bench databio_benchmark -- --quick`. |
| 35 | + |
| 36 | +## Coding Style & Naming Conventions |
| 37 | +- Formatter: rustfmt via pre-commit. Run `cargo fmt --all` before pushing. |
| 38 | +- Lints: `cargo check` runs in pre-commit; keep builds warning-free. |
| 39 | +- Naming: crates/modules `snake_case`, types/enums `PascalCase`, functions/vars `snake_case`, constants `SCREAMING_SNAKE_CASE`. |
| 40 | +- Indentation: 4 spaces; avoid long lines unless readability benefits. |
| 41 | + |
| 42 | +## Testing Guidelines |
| 43 | +- Frameworks: Rust built-in tests, `rstest` for parametrization, `tokio::test` for async. |
| 44 | +- Locations: unit tests inline in `src/`; integration tests in `sequila-core/tests/`. |
| 45 | +- Conventions: name tests descriptively (e.g., `interval_rule_eq`); include edge cases for join predicates and config options. |
| 46 | +- Coverage: no strict target; add tests for new features and bug fixes. |
| 47 | + |
| 48 | +## Commit & Pull Request Guidelines |
| 49 | +- Commits: imperative mood, concise title; optionally use prefixes (`feat:`, `fix:`, `perf:`). Reference issues/PRs where relevant. |
| 50 | +- PRs: include scope/intent, key changes, how to test (commands/queries), and performance notes if applicable. Add screenshots/log snippets when helpful. |
| 51 | +- Keep diffs focused; update README or examples when behavior changes. |
| 52 | + |
| 53 | +## Architecture & Configuration Tips |
| 54 | +- Core idea: replace/augment DataFusion planning with `SeQuiLaQueryPlanner` and an interval-join physical optimization rule. |
| 55 | +- Useful SQL settings: |
| 56 | + - `SET sequila.prefer_interval_join TO true;` |
| 57 | + - `SET sequila.interval_join_algorithm TO coitrees;` |
| 58 | + - `SET datafusion.optimizer.repartition_joins TO false;` |
| 59 | +- Bench data: export `BENCH_DATA_ROOT` to point at local datasets. |
| 60 | + |
0 commit comments