chore(compile-time): add opt-in compile-time SQL validation (query_as!, derive(Table), VS Code squigglies)

[StefanSteiner]

Summary

Adds opt-in, sqlx-style compile-time SQL validation to hyperdb-api. When the compile-time cargo feature is enabled on hyperdb-api-derive, query_as!(User, "SELECT id, name FROM users") validates the SQL against registered struct schemas at cargo build time — catching dropped/renamed columns, typos, and missing tables before they reach runtime.

The existing runtime path (Connection::fetch_all_as, #[derive(FromRow)]) is unchanged. Compile-time checking is strictly additive behind an opt-in cargo feature.

How it works

// Cargo.toml:
// hyperdb-api-derive = { version = "...", features = ["compile-time"] }

#[derive(Debug, FromRow, Table)]
#[hyperdb(table = "users", register)]   // ← registers schema at build time
struct User {
    #[hyperdb(primary_key)]
    id: i64,
    name: String,
    email: Option<String>,
}

// Validated at cargo build time when compile-time feature is on:
let users: Vec<User> = query_as!(User, "SELECT id, name, email FROM users")
    .fetch_all(&conn)?;

// Column typo → compile error:
let _ = query_as!(User, "SELECT id, nme FROM users");
// error: `User` requires column "name" but the query does not project it

// Non-existent column → compile error:
let _ = query_as!(User, "SELECT id, emai1, name FROM users");
// error: column "emai1" does not exist on any table in the query;
//        check for a typo or a renamed/dropped column

What's included

New crate: hyperdb-compile-check (standalone, not a workspace member — avoids a Cargo dep cycle)

• CompileTimeDb: one HyperProcess + one Connection behind OnceLock<parking_lot::Mutex>, shared across all macro expansions in a crate compilation
• registry: dual-indexed by Rust struct ident + SQL table name; populated at macro expansion time (not in user binary)
• dry_run: wraps SQL as WITH __hdb_q AS (<sql>) SELECT * FROM __hdb_q LIMIT 0, drives next_chunk() once (lazy TCP execution), returns ResultSchema
• error_extract: SQLSTATE-based classification (42P01/42703/42601) — no sqlparser dependency
• validate_query_as / validate_scalar_sql: bounded seed-and-retry loop (up to 8 rounds) handles multi-table JOINs where all tables need first-seeding
• Structured ValidationError variants with actionable messages for each error class (missing struct registration, unknown column, missing columns, unregistered table, syntax error)

hyperdb-api-derive additions

• #[derive(Table)]: generates impl Table { const NAME; const CREATE_SQL } from field types; with #[hyperdb(register)] + compile-time feature, registers the struct in the compile-check registry at expansion time
• query_as!(T, "sql" [, args…]): returns QueryAs<T> builder; validates SQL at build time when feature enabled
• query_scalar!(T, "sql" [, args…]): returns QueryScalar<T> builder for single-column queries; validates at build time
• #[hyperdb(primary_key)] on fields: now silently ignored by FromRow (previously caused an error when combining derive(FromRow) and derive(Table))
• Fully rewritten README.md documenting all macros, compile-time feature, supported types, and VS Code setup

hyperdb-api additions

• Table trait: const NAME: &'static str + const CREATE_SQL: &'static str
• QueryAs<T: FromRow>: fetch_all/fetch_one/fetch_optional(&conn)
• QueryScalar<T: RowValue>: same interface for scalar values

.vscode/settings.json (committed, force-added past .gitignore)

• Enables compile-time feature in rust-analyzer so bad SQL shows squigglies in VS Code
• Sets HYPERD_PATH via extraEnv for the proc-macro host
• Uses the flat-array format for rust-analyzer.cargo.features — the JSON-object form is silently ignored by RA and was the root cause of IDE validation not firing

Architecture notes

• Dep cycle resolved: hyperdb-api-derive is no longer a dep of hyperdb-api. Users import derive macros directly from hyperdb-api-derive. This is a breaking change for anyone using use hyperdb_api::FromRow as a derive macro (the trait re-export is unchanged; only the proc-macro re-export is removed).
• Feature off = zero overhead: without compile-time, query_as! is a pure pass-through; hyperdb-compile-check is not built.
• One Hyper instance per crate: ~156ms cold start amortized across all macro invocations; RA uses the same instance without re-expanding unchanged macros (salsa memoization).
• Module ordering constraint: derive(Table) structs must be in modules declared before modules containing query_as! calls (within a file, ordering is always correct). Documented in README.

Diagnostic examples

Error	Message
Column typo in SELECT	column "emai1" does not exist on any table in the query; check for a typo or a renamed/dropped column
Struct field not projected	`User` requires column "email" but the query does not project it; add it to the SELECT list or remove the field from `User`
Unregistered table	table "orders" is not registered; did you forget \#[derive(Table)] #[hyperdb(register)]`?`
Struct not registered	type \Foo` must `#[derive(Table)]` with `#[hyperdb(register)]` to be used with `query_as!``
SQL syntax error	SQL syntax error: ERROR: syntax error at or near ... (42601)
query_scalar! multi-column	query_scalar! requires exactly one projected column, but the query projects 3

Tests

• 13 unit tests in hyperdb-compile-check (no HYPERD_PATH needed)
• 10 trybuild UI tests in hyperdb-api-derive/tests/ui/ (4 pass + 6 fail with golden .stderr)
• 6 integration tests in hyperdb-api/tests/compile_time_validation_tests.rs (require HYPERD_PATH; cover full stack including JOINs)
• All existing workspace tests continue to pass

Known limitations (documented in README)

• Type checking deferred to v2: validates column names, not types. Runtime Error::Column { kind: TypeMismatch } still catches type drift.
• No parameter type checking: bind parameters are opaque at compile time (Hyper has no PREPARE metadata endpoint).
• Validates structs vs. SQL, not SQL vs. production DB: if your struct and prod schema have drifted, that remains a runtime error.

Test plan

• cargo test --workspace — all tests green
• cargo clippy --workspace --all-targets --all-features -- -D warnings — clean
• cargo clippy --workspace --all-targets -- -D warnings — clean (feature off)
• cargo test -p hyperdb-api-derive --test ui — 10 trybuild cases pass
• cargo test -p hyperdb-api --test compile_time_validation_tests — 6 integration tests pass (requires HYPERD_PATH)
• cargo build --example compile_time_validation -p hyperdb-api — example builds
• VS Code: open repo, reload window, verify squigglies appear on bad query_as! SQL