From 12694cc115cde88ef2c1743462b51118875b2888 Mon Sep 17 00:00:00 2001 From: "@mpyw" Date: Wed, 19 Aug 2026 06:46:01 +0900 Subject: [PATCH] docs: recommend pinning both the expand and build snapshots MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a TIP to the "Expanding includes for inspection" section: pin two snapshots per query — the Expand/ExpandFile output (@include-resolved, dialect- and parameter-independent) and the Build output for representative parameters (SQL + Args, or the values-embedded SQLWithArgs). The first isolates fragment-composition drift; the second captures how inputs render. The testdata/example project follows this with .expanded.sql and ..embedded.sql. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01YAydPGeSHjZvJv22oz4P6d --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 5a1b912..40e90ef 100644 --- a/README.md +++ b/README.md @@ -508,6 +508,17 @@ snapshots and for pre-execution inspection with `EXPLAIN`. expanded, err := bisql.ExpandFile(sqlFS, "users/search.sql") ``` +> [!TIP] +> Pin **two snapshots per query** as a regression guard: +> +> - **Expansion** — the `Expand`/`ExpandFile` output (`@include` resolved, still two-way). +> Dialect- and parameter-independent; isolates *what was composed*. +> - **Build** — the `SQL` + `Args` (or the values-embedded `SQLWithArgs`) for representative +> parameters, per dialect; captures *what an input produces*. +> +> The sample project under [`testdata/example`](testdata/example) does this: one +> `.expanded.sql` per query, one `..embedded.sql` per case. + ## Authoring rules Because the engine removes nothing implicitly, a template author observes the following rules.