Add bindsyntax: a seam for a non-two-way bind spelling

[mpyw]

Draft. Five commits: the seam, the implementation, and three corrections found by
measuring sqlc rather than reasoning about it.

Why

Two-way binding needs a literal at the bind site — that is what makes
/*status*/'active' run unmodified in a client. A static analyzer such as sqlc
needs a marker there instead, or it sees a constant. No single text is both.

That is why a two-way template can be fully checked by sqlc — SQL, catalog, result
columns — while its arguments stay invisible. The bind syntax is the only thing
standing in the way, and it is separable: /*%if*/ and /*%for*/ are comments
under any bind spelling, so the structure half needs no change at all.

WithBindSyntax(bindsyntax.SqlcNamed) trades the runnable-as-is property, for
values only, to get the typing back.

Form	Binds
sqlc.arg(name)	one parameter; quoting the name is what allows a dot ('c.name')
sqlc.narg(name)	one parameter; identical at build time, the distinction is for the analyzer
sqlc.slice(name)	a placeholder list, with the parens left to the template
@name	a shortcut for sqlc.arg(name) — except under MySQL

The constant is SqlcNamed, not Named: this is not a generic named-parameter
form but one tool's spelling, down to which call wrappers exist, what each promises,
and which of them a given engine supports.

The governing rule

bisql has to recognize exactly what sqlc recognizes. A spelling one of them
binds and the other does not is the single failure this arrangement exists to
avoid — sqlc would type a parameter that never gets bound, or reject a template
bisql renders fine. Every correction in this branch is an instance of that rule,
and each was found by running sqlc, not by reading its docs:

• @name is not a bind under MySQL, where it is a user variable and sqlc does
  not support the shortcut. bisql was binding it anyway, so
  select @row_number := @row_number + 1 rendered as select ? := ? + 1 with nil
  arguments. Whether the shortcut applies now depends on the dialect, as it does
  for sqlc.
• sqlc.arg(name) with a bare name is sqlc's own documented spelling and
  accepted by every engine; bisql rejected it as malformed. Accepted now, with the
  unquoted form restricted to a bare identifier because sqlc rejects an unquoted
  dotted name too.
• A prefix that could only have been a marker but cannot be one is rejected.
  @c.name bound c and rendered $1.name, without complaint. sqlc reads it the
  same way and then rejects the edited query for being invalid SQL — but that
  second step is exactly what a renderer does not have, so the spelling has to be
  refused up front.

Other implementation decisions

A bind marker is opaque text, not a comment, so it has to be recognized before
the surrounding word absorbs it — @status would otherwise lex as a single word.
Recognition of @ requires that what follows can start an identifier, so @> and
@@version are names under no dialect.

Who owns the parentheses differs, and it has to. A parenthesized test literal
is the parentheses, so the renderer replaces them. A template written for sqlc
has to be valid SQL before rendering, and in (sqlc.slice(ids)) needs its parens
written — emitting another pair would double them.

The two forms that read a test literal are rejected, not reinterpreted: the
two-way directive, which would degrade into a comment followed by a literal; and
/*^ */, which inlines its value as text, so an analyzer sees a constant and can
vouch for nothing. The alternatives are a real parameter, or a whitelisted
/*%if*/ toggle for an identifier or a sort direction.

sqlc.embed(table) needs no work. It is a result-column construct, not a bind,
and stays opaque. Worth recording that sqlc expands it into an explicit column list
in the SQL it hands back, so a renderer fed that SQL never meets the call — one fed
the original template would, and would send it to the database.

What is untouched

Block directives, @include, and every design invariant. Placeholder numbering
stays one renderer-global counter, which is precisely what lets a branch-dependent
parameter set number without gaps:

/*%if activeOnly*/ and status = @status /*%end*/     -- not taken
/*%if minAge != null*/ and age >= @min_age /*%end*/  -- $1
/*%for kw in keywords*/ and name like @kw /*%end*/   -- $2, $3

No SQL grammar parsing either: the new code scans identifiers, not syntax.

Verification

mise run check clean: fmt, build, vet, golangci-lint (0 issues), deadcode,
go test -race. Tests cover the lexer (recognition and its boundaries, line
tracking across a multi-line marker), the parser (round-tripping Text() == src,
list expansion, the rejections), and the end-to-end build for every form and both
dialect rules. Every silent render the corrections remove was measured first, so
the tests assert against what the code did rather than what it was meant to do.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.50549% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.12%. Comparing base (bc443d9) to head (05a9539).

Files with missing lines	Patch %	Lines
bindsyntax/bindsyntax.go	94.49%	6 Missing ⚠️
internal/sqltmpl/parser/parser.go	84.00%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #29      +/-   ##
==========================================
- Coverage   96.52%   96.12%   -0.41%     
==========================================
  Files          11       12       +1     
  Lines         951     1109     +158     
==========================================
+ Hits          918     1066     +148     
- Misses         21       29       +8     
- Partials       12       14       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mpyw]

Closing unmerged. The measurements hold; the placement was wrong.

main never took any of this, so there is nothing to revert — the branch stays as
the record.

Why this does not belong in bisql

The mode cost 422 lines added to bisql's core (~1480 lines), and every one of them
is a conditional for the other product: Rules/AtForm, the two rejections,
token.NamedBind, BindValue.Test == nil as a second state, ExpandList, and the
split in visitBind over who owns the parentheses.

Worse, the last commit put knowledge of sqlc into bisql: that sqlc does not
support the @ shortcut for MySQL, hardcoded as a dialect-name comparison. That is
a fact about a tool bisql does not depend on, it is undocumented behaviour that
will drift, and bisql is the wrong place to keep it.

And it dilutes the definition in CLAUDE.md. bisql is a two-way SQL template engine;
this mode is explicitly not two-way, and it was accumulating carve-outs against
that identity rather than extending it.

Where it goes

mpyw/sqlc-gen-go-dynamic, as a sibling with its own directive engine. That engine
is not a fork of this one — it is a strict simplification, because the plugin needs
none of what makes this one complex:

Dropped	Why
preprocess + include.go (247 lines)	@include cannot work downstream of sqlc: the fragment is a comment to sqlc, so its binds are never typed
dialect.Literal / FormatLiteral	exists for /*^ */, which that mode rejects
bindReducer, literalReducer, test-literal collection	the two-way bind form only
Oracle, SQL Server	sqlc has no such engine
Rules, the rejections, the parenthesis split	unnecessary once there is one bind syntax

Roughly 1900 lines become under 1000, and none of them are branches on a mode.

The cost is a second lexer to maintain. The shared part — quote and comment
scanning, block nesting, verbatim emit against one global counter — is small and
stable, and the parts where bugs actually live are the parts that are not shared.
If the same bug ever has to be fixed twice, that is the signal to extract a shared
core; doing it now would mean committing to the internal AST as public API, which
CLAUDE.md deliberately avoids.

What carries over

Everything measured against sqlc v1.31.1, which is the durable part of this branch:

• @name is a bind under PostgreSQL and SQLite but not MySQL, where it is a user
  variable.
• A call argument may be bare or single-quoted, and only the quoted spelling may
  carry a dot.
• @c.name and sqlc.arg(c.name) have to be refused up front: sqlc reads them the
  same way and then rejects the edited query, and a renderer has no such second
  step.
• The template owns the parentheses around a placeholder list, since it had to be
  valid SQL before rendering.
• /*^ */ has to be refused, because an analyzer sees a constant there and can
  vouch for nothing.

🤖 Generated with Claude Code