feat: splice SQL fragments into a statement's sentinel comments

[iamralch]

The third of the three. sqlx-cel makes a fragment out of a CEL expression, sqlx-aip makes two out of an AIP List request, and nothing put one in a query — so every caller grew its own copy of the substitution.

This is pgxquery's job at a different moment: pgx has a QueryRewriter hook, so there it happens as the query is sent. sqlx has no such hook, so it happens where the string is built, and it is a function rather than an interface.

let sql = splice(LIST_VOLUMES, &[
    ("where", Some(r#""title" = $3"#)),
    ("order_by", Some(r#""created_at" DESC"#)),
])?;

The convention is pgxquery's, unchanged — the connective lives inside the comment, so the statement decides how a fragment joins to what surrounds it, and an unspliced statement runs as written because sentinels are comments.

Two departures from pgxquery, both deliberate

A fragment with no sentinel to go into is an error. The predicate would silently not apply, and a dropped predicate widens a result set rather than emptying it — plausible rows, no error, production. The reverse is not an error: a sentinel this call says nothing about is left alone, since substituting what you weren't given is deciding the statement is wrong.

Renumbering is the fallback, not the path. placeholder_count says where a statement stops binding, so a producer that takes a starting offset — sqlx-cel's Options, sqlx-aip's rewrite_with (sqlx-contrib/sqlx-aip#9) — emits the right numbers to begin with and nothing re-reads the SQL. shift remains for a fragment that arrived numbered from $1.

What to look at

• src/scan.rs is most of the code. A $1 inside a string literal, a quoted identifier, a line or block comment, or a dollar-quoted body is text, not a parameter — renumbering one yields SQL that still parses and binds the wrong value. Block comments nest in PostgreSQL, so "find the next */" is also not enough. This is the part worth reviewing closely; it's ported from pgxquery's shiftPlaceholders and shares its cases.
• No dependencies, not even sqlx. &str in, String out; a caller splicing into a hand-written query shouldn't acquire a driver for it. sqlx is a dev-dependency for the round trip only.
• splice takes a slice of (name, Option<&str>) rather than hardcoding where/order_by as pgxquery does, so query.limit or anything else works without a change here.

Testing

cargo fmt --check, cargo clippy --all-targets, cargo test, cargo doc --no-deps and nix flake check are all clean: 33 tests.

The 4 in tests/postgres.rs skipped — no DATABASE_URL where this was written. They're the ones that check a spliced statement actually runs, which text assertions can't stand in for, so CI's devcontainer Postgres is where that claim gets tested. The harness asserts DATABASE_URL is set when CI is, so a skip there fails rather than passing quietly.