Chore/licence

AGENT.md

@@ -0,0 +1,165 @@
+# KiteSQL Agent Guide
+
+This document defines the engineering principles, code style, and contribution expectations
+for the KiteSQL project.
+
+KiteSQL is a lightweight, simple, low-dependency OLTP database.
+All code contributions (human or AI-generated) must follow the rules below.
+
+---
+
+## 1. Project Philosophy
+
+KiteSQL prioritizes:
+
+- Lightweight design
+- Simple and explicit logic
+- Low dependency footprint
+- High correctness through testing
+- Readable code over clever code
+
+This is an OLTP-oriented system.
+Predictability, correctness, and maintainability are more important than micro-optimizations.
+
+---
+
+## 2. Testing Requirements (MANDATORY)
+
+### 2.1 Makefile Is the Source of Truth
+
+All test commands must be defined and discoverable in the Makefile.
+
+This includes (but is not limited to):
+
+- Unit tests
+- Integration tests
+- SQL behavior tests
+- Regression tests
+
+If a test cannot be triggered via make, it is considered incomplete.
+
+Examples:
+```
+make test
+make test-unit
+make test-integration
+```
+
+PRs must not introduce hidden, ad-hoc, or undocumented test commands.
+
+---
+
+### 2.2 Tests Are Not Optional
+
+- Every PR must include sufficient unit tests
+- New functionality must be covered by tests
+- Bug fixes must include regression tests
+
+If logic is complex, tests are preferred over comments.
+
+Untested code is considered incomplete code.
+
+---
+
+### 2.3 Expand Test Coverage When Touching Code
+
+When modifying existing functionality, contributors are expected to:
+
+- Identify related edge cases or failure modes
+- Add unit tests for behaviors that were previously untested
+- Strengthen coverage around logic affected by the change
+
+This applies even if the original change request does not explicitly ask for new tests.
+
+If you are already touching the code, it is the best time to fix missing tests.
+
+PRs that modify logic but leave obvious test gaps untouched may be rejected.
+
+---
+
+## 3. Code Simplicity Rules
+
+### 3.1 Prefer Simple Code
+
+- Prefer straightforward control flow
+- Avoid unnecessary abstractions
+- Avoid premature generalization
+- Avoid clever tricks that reduce readability
+
+If something can be written clearly using fewer concepts, do that.
+
+---
+
+### 3.2 Low Comments, High Signal
+
+- Do not comment obvious code
+- Do not restate what the code already expresses
+- Prefer self-explanatory naming
+
+However, the following must include short, precise comments:
+
+- Complex logic
+- Non-obvious invariants
+- Encoding, ordering, or correctness-sensitive behavior
+
+Comments should explain why, not what.
+
+Example:
+```rust
+// Keys are encoded in mem-comparable form to preserve lexicographical ordering
+```
+
+---
+
+## 4. Code Reuse & Structure
+
+### 4.1 Reuse Over Duplication
+
+- Prefer extracting shared logic over copy-pasting
+- Shared behavior should live in a single place
+- Avoid near-duplicate implementations with small differences
+
+If code looks similar in multiple places, it probably wants to be reused.
+
+---
+
+### 4.2 Minimal APIs
+
+- Public APIs should be minimal and intentional
+- Avoid exposing internal details
+- Keep modules small, focused, and cohesive
+
+---
+
+## 5. Dependency Policy
+
+- Dependencies are costly
+- Every new dependency must be justified
+- Prefer standard library solutions where possible
+- Avoid heavy frameworks or macro-heavy crates unless strictly necessary
+
+KiteSQL aims to stay easy to build, easy to audit, and easy to understand.
+
+---
+
+## 6. PR Expectations
+
+A valid PR should:
+
+- Compile cleanly
+- Pass all tests via make
+- Include new tests if behavior changes
+- Improve or extend test coverage when touching existing code
+- Keep code simple and readable
+- Reuse existing abstractions where possible
+- Follow the spirit of KiteSQL: simple, lightweight, correct
+
+PRs that increase complexity without clear benefit may be rejected.
+
+---
+
+## 7. Final Principle
+
+If the code is hard to understand, it is probably wrong.
+
+Clarity is a feature.

Makefile

@@ -0,0 +1,25 @@
+# Helper variables (override on invocation if needed).
+CARGO ?= cargo
+WASM_PACK ?= wasm-pack
+SQLLOGIC_PATH ?= tests/slt/**/*.slt
+
+.PHONY: test test-wasm test-slt test-all wasm-build
+
+## Run default Rust tests in the current environment (non-WASM).
+test:
+	$(CARGO) test
+
+## Build the WebAssembly package (artifact goes to ./pkg).
+wasm-build:
+	$(WASM_PACK) build --release --target nodejs
+
+## Execute wasm-bindgen tests under Node.js (wasm32 target).
+test-wasm:
+	$(WASM_PACK) test --node --release
+
+## Run the sqllogictest harness against the configured .slt suite.
+test-slt:
+	$(CARGO) run -p sqllogictest-test -- --path $(SQLLOGIC_PATH)
+
+## Convenience target to run every suite in sequence.
+test-all: test test-wasm test-slt

benchmarks/query_benchmark.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use criterion::{criterion_group, criterion_main, Criterion};
 use indicatif::{ProgressBar, ProgressStyle};
 use kite_sql::db::{DataBaseBuilder, ResultIter};

examples/hello_world.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #![cfg(not(target_arch = "wasm32"))]
 
 use kite_sql::db::{DataBaseBuilder, ResultIter};

examples/transaction.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #![cfg(not(target_arch = "wasm32"))]
 
 use kite_sql::db::{DataBaseBuilder, ResultIter};

kite_sql_serde_macros/src/lib.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 mod reference_serialization;
 
 use proc_macro::TokenStream;

kite_sql_serde_macros/src/reference_serialization.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use darling::ast::Data;
 use darling::{FromDeriveInput, FromField, FromVariant};
 use proc_macro2::{Ident, Span, TokenStream};

src/bin/server.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use async_trait::async_trait;
 use clap::Parser;
 use futures::stream;

src/binder/aggregate.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use ahash::RandomState;
 use itertools::Itertools;
 use sqlparser::ast::{Expr, OrderByExpr};

src/binder/alter_table.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use sqlparser::ast::{AlterTableOperation, ObjectName};
 
 use std::sync::Arc;

src/binder/analyze.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use crate::binder::{lower_case_name, Binder, Source};
 use crate::errors::DatabaseError;
 use crate::planner::operator::analyze::AnalyzeOperator;

src/binder/copy.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use std::path::PathBuf;
 use std::str::FromStr;
 use std::sync::Arc;

src/binder/create_index.rs

@@ -1,3 +1,17 @@
+// Copyright 2024 KipData/KiteSQL
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 use crate::binder::{lower_case_name, Binder, Source};
 use crate::errors::DatabaseError;
 use crate::expression::ScalarExpression;