dimgigov
6bfc5b3a3c
CI / test (push) Has been cancelled
CI / verify (push) Has been cancelled
Clients CI / build-server (push) Has been cancelled
Clients CI / test-python (push) Has been cancelled
Clients CI / test-javascript (push) Has been cancelled
Clients CI / test-nim (push) Has been cancelled
Clients CI / test-rust (push) Has been cancelled
- Pure Nim wire protocol client (async + sync, no C FFI) - Query Builder: fluent API, SQL generator, execution, transactions - Schema Builder: create/alter/drop tables, column operations - Connection pool with aging and timeout handling - ORM integration via compile-time DB_BARADB switch - Tests: test_open, test_query - Documentation: README.md, PLAN_BARADB.md
202 lines
9.6 KiB
Plaintext
202 lines
9.6 KiB
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
プロジェクトルール
|
|
===
|
|
|
|
## 0. 規範表現（RFC 2119）と Lint方針
|
|
|
|
このドキュメントの規範キーワードは以下の意味で扱う。
|
|
- **MUST**: 必須。違反はレビューで差し戻し対象
|
|
- **SHOULD**: 強い推奨。逸脱時は理由を記録する
|
|
- **MAY**: 任意。採用時は周辺整合性を優先する
|
|
- **MUST NOT**: 禁止。明示的な合意なしに導入してはならない
|
|
|
|
各ルールには Rule ID を付与する。
|
|
- 形式: `SYW-<DOMAIN>-<NNN>`
|
|
- 併記形式: `[ID][LEVEL][CHECK]`
|
|
- `CHECK` の意味:
|
|
- `grep`: 文字列や配置で確認しやすい
|
|
- `manual`: レビューで確認する
|
|
- `test`: テストで確認する
|
|
- `doc`: 文書整合の確認
|
|
|
|
本文とルール一覧が矛盾した場合は、ルール一覧を優先する。
|
|
|
|
### 0.1 ルール一覧（要約）
|
|
|
|
| ID | LEVEL | CHECK | 対象 | 要件（要約） |
|
|
|---|---|---|---|---|
|
|
| SYW-GOAL-001 | MUST | manual | 全体 | 本リポジトリは Nim による RDB 向け query builder / migration / seeder を中核成果物とする |
|
|
| SYW-GOAL-002 | MUST | manual | API | Laravel Query Builder / Orator に学んだ直感的で連鎖可能な API を保つ |
|
|
| SYW-ARCH-001 | MUST | manual | 設計 | DB差分は driver 実装へ閉じ込め、公開 API は可能な限り共通化する |
|
|
| SYW-ARCH-002 | MUST NOT | manual | 設計 | 一時的な場当たり分岐を公開 API に持ち込まない |
|
|
| SYW-QB-001 | MUST | test | Query Builder | SQL 生成は決定的で、同じ入力に対し同じクエリ文字列・束縛順序を返す |
|
|
| SYW-QB-002 | MUST | manual | Query Builder | メソッドチェーンは可読性を優先し、Laravel/Orator 利用者が推測可能な命名を採用する |
|
|
| SYW-QB-003 | MUST NOT | manual | Query Builder | RDB 向け API に暗黙の破壊的副作用を持たせない |
|
|
| SYW-SCHEMA-001 | MUST | test | Migration | migration は冪等に再実行判定でき、履歴テーブルと整合する |
|
|
| SYW-SCHEMA-002 | MUST | test | Schema Builder | create / alter / drop は DB ごとの差異を吸収しつつ意味論を維持する |
|
|
| SYW-SEED-001 | MUST | test | Seeder | seeder は空判定または条件判定に基づき安全に再実行できる |
|
|
| SYW-COMPAT-001 | MUST | manual | 互換性 | 既存公開 API の破壊的変更は、必要性・移行方針・影響範囲を文書化する |
|
|
| SYW-TEST-001 | MUST | test | テスト | 修正した機能レイヤに対応するテストを追加または更新する |
|
|
| SYW-TEST-002 | SHOULD | test | テスト | DB 横断の共通仕様は複数 driver で検証する |
|
|
| SYW-DOC-001 | MUST | doc | ドキュメント | README / documents / ルール文書は、公開仕様変更時に同期する |
|
|
| SYW-SCOPE-001 | MUST NOT | manual | スコープ | ORM 全面実装を前提にせず、query builder・schema builder の完成度を優先する |
|
|
|
|
## 1. 目的・スコープ
|
|
|
|
### 1.1 達成目標
|
|
|
|
[SYW-GOAL-001][MUST][manual]
|
|
このプロジェクトの達成目標は、**Nim 言語で Laravel の Query Builder / ORM 的な記述感と Python Orator の使いやすさを参考にした、RDB 向け query builder を実装・改善・保守すること**である。
|
|
|
|
[SYW-GOAL-002][MUST][manual]
|
|
中核機能は以下の 3 系統である。
|
|
- Query Builder
|
|
- Migration / Schema Builder
|
|
- Seeder
|
|
|
|
[SYW-GOAL-003][MUST][manual]
|
|
利用者は「生 SQL を毎回手で組み立てなくても、読みやすいメソッドチェーンで安全に RDB を扱える」ことを期待している。実装判断は常にこの期待を優先する。
|
|
|
|
### 1.2 主要スコープ
|
|
|
|
[SYW-SCOPE-001][MUST][manual]
|
|
主要スコープは以下である。
|
|
- SQLite / PostgreSQL / MySQL / MariaDB などの RDB 向け query builder
|
|
- create / alter / drop を扱う schema builder
|
|
- migration 履歴管理
|
|
- 初期データ投入用 seeder
|
|
- 非同期実行を前提とした接続・実行モデル
|
|
|
|
[SYW-SCOPE-002][SHOULD][manual]
|
|
既存コードベースに SurrealDB 実装が存在していても、判断に迷った場合はまず RDB 向け API 品質を優先する。
|
|
|
|
### 1.3 非スコープ
|
|
|
|
[SYW-SCOPE-003][MUST NOT][manual]
|
|
以下は明示的な要件がない限り優先しない。
|
|
- Active Record 的な重い ORM 機能の全面拡張
|
|
- マジックに依存した暗黙変換の追加
|
|
- driver ごとに大きく振る舞いが異なる独自 API の増殖
|
|
|
|
## 2. 設計原則
|
|
|
|
### 2.1 API 原則
|
|
|
|
[SYW-ARCH-001][MUST][manual]
|
|
公開 API は driver 差分より先に、利用者の記述体験を基準に設計する。各 driver の都合は内部実装で吸収する。
|
|
|
|
[SYW-QB-002][MUST][manual]
|
|
メソッド名・引数順・返り値は、Laravel Query Builder / Orator を知る利用者が高い確率で推測できる形を優先する。
|
|
|
|
[SYW-QB-003][MUST NOT][manual]
|
|
`select`, `where`, `join`, `insert`, `update`, `delete`, `first`, `find`, `get` などの基本操作に、利用者が予期しない破壊的副作用を持ち込んではならない。
|
|
|
|
[SYW-COMPAT-001][MUST][manual]
|
|
公開 API の破壊的変更を行う場合は、少なくとも以下を変更箇所に残す。
|
|
- 何が壊れるか
|
|
- なぜ必要か
|
|
- 既存利用者の移行方法
|
|
|
|
### 2.2 実装分離
|
|
|
|
[SYW-ARCH-002][MUST NOT][manual]
|
|
「特定 driver だけ通すための場当たり的 if 文」を上位 API 層へ散在させてはならない。分岐は generator / lib / model など責務のある層へ閉じ込める。
|
|
|
|
[SYW-ARCH-003][MUST][manual]
|
|
責務分離の目安は以下とする。
|
|
- 接続管理: `connection` 系
|
|
- API 入口と共通操作: `query_builder` / `schema_builder`
|
|
- DB 方言差分: `models/*/query/*`, `libs/*`
|
|
- 実行・変換: `*_exec`, `*_types`, `*_query`
|
|
|
|
[SYW-ARCH-004][SHOULD][manual]
|
|
新機能は、まず共通仕様を言語化してから driver 差分へ展開する。最初に 1 driver だけ特殊実装へ逃がさない。
|
|
|
|
## 3. Query Builder ルール
|
|
|
|
[SYW-QB-001][MUST][test]
|
|
同じ builder 入力は、同じ SQL 文字列と同じ bind 順序を生成しなければならない。出力が非決定的になる変更は禁止する。
|
|
|
|
[SYW-QB-004][MUST][manual]
|
|
where 句、join、group by、order by、limit / offset、paginate などの句の結合順は、利用者の記述順と SQL としての自然順を壊さない。
|
|
|
|
[SYW-QB-005][SHOULD][manual]
|
|
値の埋め込みよりも、既存のプレースホルダ・エスケープ・型変換の仕組みを優先して使う。
|
|
|
|
[SYW-QB-006][MUST][test]
|
|
`first` / `find` / `get` の空結果時の振る舞いは既存仕様を維持する。`Option` や空シーケンスの扱いを無言で変えてはならない。
|
|
|
|
[SYW-QB-007][SHOULD][manual]
|
|
ログ出力やデバッグ補助を追加する場合は、通常経路の性能や API 純度を汚さない。
|
|
|
|
## 4. Migration / Schema Builder ルール
|
|
|
|
[SYW-SCHEMA-001][MUST][test]
|
|
migration は履歴テーブルにより再実行可否を判定できなければならない。二重適用や履歴不整合を起こす変更は禁止する。
|
|
|
|
[SYW-SCHEMA-002][MUST][test]
|
|
`create`, `alter`, `drop`, `rename`, `add column`, `change column`, `drop column` は、DB ごとの差異があっても利用者にとって一貫した意味を維持する。
|
|
|
|
[SYW-SCHEMA-003][MUST][manual]
|
|
破壊的な schema 操作を追加・変更する場合は、ロールバック不能性やデータ移行影響を必ず確認する。
|
|
|
|
[SYW-SCHEMA-004][SHOULD][manual]
|
|
column 定義 API は Laravel ライクな表現を優先し、命名やオプションの意味が直感に反しないようにする。
|
|
|
|
## 5. Seeder ルール
|
|
|
|
[SYW-SEED-001][MUST][test]
|
|
seeder は再実行時に重複データを無制限に増やさないよう、空テーブル判定または列条件判定を用いる既存思想を維持する。
|
|
|
|
[SYW-SEED-002][SHOULD][manual]
|
|
サンプル seeder と実装が乖離した場合は、利用者が最初に触れる example を優先して同期する。
|
|
|
|
## 6. テスト・品質保証
|
|
|
|
[SYW-TEST-001][MUST][test]
|
|
コード変更時は、影響する最小レイヤのテストを追加または更新する。
|
|
- query 生成を変えたら query テスト
|
|
- schema 操作を変えたら schema / create_schema テスト
|
|
- トランザクションを変えたら transaction テスト
|
|
- utility を変えたら utils テスト
|
|
|
|
[SYW-TEST-002][SHOULD][test]
|
|
共通 API の変更は、可能な限り SQLite だけでなく PostgreSQL / MySQL / MariaDB 系にも同種の検証を広げる。
|
|
|
|
[SYW-TEST-003][MUST][manual]
|
|
テスト追加が難しい場合は、その理由と未検証リスクを作業記録へ残す。
|
|
|
|
## 7. ドキュメント・例・後方互換
|
|
|
|
[SYW-DOC-001][MUST][doc]
|
|
公開仕様を変えたら、必要に応じて以下を同期する。
|
|
- `README.md`
|
|
- `documents/rdb/*.md`
|
|
- `example/`
|
|
- `.cursor/rules/*.mdc`
|
|
|
|
[SYW-DOC-002][SHOULD][doc]
|
|
サンプルコードは「最短で使い方が伝わる」ことを優先し、実装とズレた古い記法を放置しない。
|
|
|
|
## 8. 実装判断の優先順位
|
|
|
|
[SYW-PRIO-001][MUST][manual]
|
|
判断に迷った場合の優先順位は以下とする。
|
|
1. 利用者にとって API が自然か
|
|
2. 既存公開仕様を壊さないか
|
|
3. 複数 RDB で意味が揃うか
|
|
4. 内部実装が責務分離されているか
|
|
5. テストと文書で保守できるか
|
|
|
|
## 9. このプロジェクトで避けること
|
|
|
|
[SYW-ANTI-001][MUST NOT][manual]
|
|
以下は避ける。
|
|
- 一部 driver だけを通すための公開 API 汚染
|
|
- テストなしの SQL 生成変更
|
|
- migration 履歴や seeder 冪等性を壊す変更
|
|
- README と実装の乖離放置
|
|
- Nim らしさよりも複雑なマジックを優先すること
|