|
| 1 | +{ |
| 2 | + "repo_notes": [ |
| 3 | + { |
| 4 | + "content": "KiteSQL is a lightweight embedded OLTP-oriented relational database for Rust. The main crate is `kite_sql`; important entry points are `src/lib.rs`, `src/db.rs`, `README.md`, `docs/features.md`, and `docs/transaction-isolation.md`. Treat the project as both a SQL engine and a Rust-native API/ORM surface." |
| 5 | + }, |
| 6 | + { |
| 7 | + "content": "Document the core query path explicitly: SQL text or ORM builders enter through `Database` APIs in `src/db.rs`; parser support is under `src/parser`; binding and semantic analysis are under `src/binder`; logical/physical plan structures are under `src/planner`; optimizer rules and statistics are under `src/optimizer`; executors are under `src/execution`; storage transactions and KV encoding are under `src/storage`." |
| 8 | + }, |
| 9 | + { |
| 10 | + "content": "Storage is central to this repository. `src/storage/mod.rs` defines the `Storage`, `Transaction`, and checkpoint-related traits; `memory.rs`, `rocksdb.rs`, and `lmdb.rs` implement backends behind Cargo feature gates; `table_codec.rs` is correctness-sensitive because it defines table, index, and metadata key/value encoding." |
| 11 | + }, |
| 12 | + { |
| 13 | + "content": "The ORM is feature-gated by `orm`. Runtime ORM APIs live in `src/orm`, while derive macros live in the workspace crate `kite_sql_serde_macros`. The ORM frontend binds directly into core expressions and logical plans; it is not a SQL string generator." |
| 14 | + }, |
| 15 | + { |
| 16 | + "content": "Use the Makefile as the source of truth for development workflows. Important targets include `make test`, `make test-slt`, `make test-wasm`, `make test-python`, `make check`, and TPCC-related targets. SQL behavior coverage lives mainly in `tests/slt`, with the harness in `tests/sqllogictest`." |
| 17 | + } |
| 18 | + ], |
| 19 | + "pages": [ |
| 20 | + { |
| 21 | + "title": "Project Overview", |
| 22 | + "purpose": "Explain KiteSQL's goals, workspace layout, Cargo features, supported frontends, and the high-level architecture of the embedded database.", |
| 23 | + "parent": null |
| 24 | + }, |
| 25 | + { |
| 26 | + "title": "Public API and Database Lifecycle", |
| 27 | + "purpose": "Document `src/lib.rs` and `src/db.rs`, including `DataBaseBuilder`, `Database`, transaction lifecycle, built-in functions, query execution entry points, and feature-gated builders.", |
| 28 | + "parent": "Project Overview" |
| 29 | + }, |
| 30 | + { |
| 31 | + "title": "SQL Frontend: Parser and Binder", |
| 32 | + "purpose": "Document how SQL statements are parsed and bound, covering `src/parser` and `src/binder`, statement preparation, semantic checks, catalog lookup, expression binding, and statement-specific binder modules.", |
| 33 | + "parent": "Project Overview" |
| 34 | + }, |
| 35 | + { |
| 36 | + "title": "Logical Plans and Operators", |
| 37 | + "purpose": "Document `src/planner`, `PlanArena`, `LogicalPlan`, operator modules, schema derivation, child plan structure, and how binder output becomes an executable plan.", |
| 38 | + "parent": "Project Overview" |
| 39 | + }, |
| 40 | + { |
| 41 | + "title": "Optimizer and Statistics", |
| 42 | + "purpose": "Document `src/optimizer`, heuristic batches, normalization and implementation rules, statistics metadata, histograms, sketches, and how physical options are selected.", |
| 43 | + "parent": "Logical Plans and Operators" |
| 44 | + }, |
| 45 | + { |
| 46 | + "title": "Execution Engine", |
| 47 | + "purpose": "Document the volcano-style execution engine in `src/execution`, including `Executor`, `ExecArena`, DDL apply handling, DQL nodes, DML nodes, joins, aggregation, subqueries, and explain output.", |
| 48 | + "parent": "Project Overview" |
| 49 | + }, |
| 50 | + { |
| 51 | + "title": "Storage, Transactions, and Encoding", |
| 52 | + "purpose": "Document `src/storage`, including storage traits, transaction isolation, in-memory/RocksDB/LMDB implementations, checkpoint capability, table and index encoding, caches, tuple iteration, and metadata persistence.", |
| 53 | + "parent": "Project Overview" |
| 54 | + }, |
| 55 | + { |
| 56 | + "title": "Catalog, Types, Expressions, and Functions", |
| 57 | + "purpose": "Document `src/catalog`, `src/types`, `src/expression`, and `src/function`, including table/view metadata, logical/data values, serialization, evaluators, scalar and table functions, and expression simplification.", |
| 58 | + "parent": "Project Overview" |
| 59 | + }, |
| 60 | + { |
| 61 | + "title": "ORM and Derive Macros", |
| 62 | + "purpose": "Document the feature-gated ORM in `src/orm` and the `kite_sql_serde_macros` crate, including `Model`, `Projection`, migrations, typed query/mutation builders, tuple mapping, and macro-generated metadata.", |
| 63 | + "parent": "Project Overview" |
| 64 | + }, |
| 65 | + { |
| 66 | + "title": "Shell, WebAssembly, and Python Bindings", |
| 67 | + "purpose": "Document user-facing integrations: `src/bin/shell.rs`, `src/wasm.rs`, `src/python.rs`, examples under `examples`, and the relevant Cargo features and build commands.", |
| 68 | + "parent": "Project Overview" |
| 69 | + }, |
| 70 | + { |
| 71 | + "title": "Testing Strategy", |
| 72 | + "purpose": "Document the Makefile-driven test workflow, unit/integration tests, SQL logic tests in `tests/slt`, the `tests/sqllogictest` harness, macro tests, WASM tests, and expected coverage practices from `AGENT.md`.", |
| 73 | + "parent": "Project Overview" |
| 74 | + }, |
| 75 | + { |
| 76 | + "title": "TPC-C Benchmark", |
| 77 | + "purpose": "Document the `tpcc` workspace crate, supported backends, dual validation mode, scripts, Makefile targets, and how benchmark output should be interpreted.", |
| 78 | + "parent": "Project Overview" |
| 79 | + }, |
| 80 | + { |
| 81 | + "title": "Contribution and Maintenance Guide", |
| 82 | + "purpose": "Summarize repository-specific engineering expectations from `AGENT.md`: simple code, low dependencies, Makefile-visible tests, correctness-first changes, and storage/encoding caution areas.", |
| 83 | + "parent": "Project Overview" |
| 84 | + } |
| 85 | + ] |
| 86 | +} |
0 commit comments