fix(drift): compare SQL expressions in ClickHouse's canonical form

[alvarogar4]

Summary

Fixes #195. chkit drift reported permanent, unfixable drift whenever a schema expression was spelled differently from how ClickHouse stores it. ClickHouse runs a full expression printer on the way in — it spaces argument separators and operators, adds precedence parentheses (n*2+1 → (n * 2) + 1), and rewrites INTERVAL 5 YEAR → toIntervalYear(5). So a skip index / PARTITION BY / ORDER BY / TTL written cityHash64(a,b) is stored cityHash64(a, b), and chkit check failed in CI on a difference no migration could resolve.

No local string normalizer can reproduce ClickHouse's precedence/INTERVAL rewriting, so only ClickHouse can produce the canonical form. drift now normalizes expressions through the server's own formatter.

How it works

• The drift command collects every SQL fragment across the compared tables — index expressions, TTL, key/partition clause elements, and SELECT-projection queries — at the exact granularity they're compared.
• It formats them all in one batched round-trip via formatQuerySingleLineOrNull, which returns NULL for a fragment it can't parse instead of failing the whole batch.
• A map-backed SqlCanonicalizer is injected into compareTableShape. Each field falls back to the existing string normalization when a fragment isn't in the map — an older server without the function, a parse failure, or offline — so behavior is never worse than today.
• compareTableShape stays pure and synchronous; the ClickHouse call lives in the async payload builder. New @chkit/clickhouse export: canonicalizeSqlFragments.

Test plan

• Unit: a skip-index expression differing only in comma spacing reads clean with the canonicalizer and drifts without it; a genuinely different expression (sipHash64 vs cityHash64) still drifts; collectTableSqlFragments gathers the right fragments at the right granularity
• canonicalizeSqlFragments unit tests (mock executor): SELECT-prefix stripping, no-wrap query mode, NULL omission, quote/backslash escaping, empty-input short-circuit
• Mutation-checked — making the comparer ignore the canonicalizer fails the reads-clean test
• Offline path preserved: existing drift suite green unchanged (the fallback path)
• Full suites green: core (296), clickhouse (36), cli (265), plugin-pull (26), plugin-obsessiondb (149); typecheck/lint/docs build clean
• Live e2e against ClickHouse 26.3 through the real CLI: a table whose skip index is written cityHash64(a,b) and TTL INTERVAL 30 DAY — both stored reformatted by ClickHouse — now reports Drifted: no (was index_mismatch + ttl_mismatch)

Scope

Covers the fragment types the issue named (skip indexes, TTL, PARTITION BY) plus key clauses and SELECT-projection queries. The canonical snapshot form is left untouched — this is a drift-comparison change only, so no existing snapshots churn on upgrade. Index-only projection expressions keep their existing normalizer (already comma-spaced; operator expressions there are rare).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Biy2vG7iixRiBsBBsFg5Nu

[alvarogar4]

Ran a high-effort adversarial review on this PR. It surfaced one real robustness gap, now fixed in the latest commit:

Batching (fixed). canonicalizeSqlFragments inlined every fragment across all compared tables into a single query. On a large schema the string-literal array could exceed ClickHouse's default max_query_size (256 KiB), throw, and — because the error is caught and falls back — silently revert the whole drift run to string comparison, no-opping the fix precisely on the large schemas that need it. Fragments are now split into batches bounded well under the limit (128 KB of literals each), run as separate queries and merged. New test forces multiple batches and asserts each query stays bounded while all fragments still map.

The review's other two flags were verified and refuted: the collector/comparer are in exact lockstep today (no silent no-op), and the swallow-and-fall-back is intended, documented graceful degradation. One low-severity efficiency note (fragments normalized twice per run) I left as-is deliberately — it keeps compareTableShape pure and the collector separate, and the cost is a cheap regex on short strings.

The sibling PRs got the same scrutiny: #200 was fuzzed old-vs-new (~1M inputs/function) and found behavior-preserving with no defects; #199 is a small denylist with a regression + mutation test.