Deepen query parameter expansion locality by mmkal · Pull Request #113 · iterate/sqlfu

mmkal · 2026-05-14T15:37:30Z

Summary

This architecture pass extracts query parameter expansion out of the broad generated query boundary module. SQL parameter scanning, inline expansion inference, analysis-SQL rewriting, and reusable replacement helpers now live behind packages/sqlfu/src/typegen/query-parameters.ts instead of being embedded in typegen/index.ts.

The generated query boundary stays user-compatible; this is an internal locality/depth change with focused tests on the new module interface.

Why

packages/sqlfu/src/typegen/index.ts mixed generated wrapper rendering, query document loading, validator emission, catalog writing, schema materialization, and named-parameter expansion. Parameter expansion has its own invariants: comment/string-safe scanning, object-field params, list params, row-list params, and generated runtime SQL. Moving those behind one module gives future changes better locality and lets tests exercise that behavior without going through full fixture generation.

Verification

Architecture branch:

pnpm exec oxfmt --check packages/sqlfu/src/typegen/index.ts packages/sqlfu/src/typegen/query-parameters.ts packages/sqlfu/test/generate/query-parameters.test.ts
pnpm --filter sqlfu typecheck
pnpm --filter sqlfu build
pnpm --filter sqlfu test --run test/generate/query-parameters.test.ts test/generate/runtime.test.ts
pnpm --filter sqlfu test --run test/generate/fixtures.test.ts

Replacement branches:

Use sqlite3-parser for schemadiff reference analysis #111 branch: pnpm --filter sqlfu typecheck; pnpm --filter sqlfu test --run test/schemadiff/fixtures.test.ts test/schemadiff/plumbing.test.ts test/generate/query-parameters.test.ts
Add generated query casing boundary #108 branch: pnpm --filter sqlfu typecheck; pnpm --filter sqlfu test --run test/generate/query-parameters.test.ts test/generate/runtime.test.ts; pnpm --filter sqlfu test --run test/generate/fixtures.test.ts
Fix sqlite-wasm named parameter binding #101 branch: pnpm --filter sqlfu typecheck; pnpm --filter @sqlfu/ui typecheck; pnpm --filter sqlfu test --run test/adapters/sqlite-wasm.test.ts test/sqlite-text.test.ts test/generate/query-parameters.test.ts; pnpm --filter @sqlfu/ui exec vitest run src/demo/browser-host.test.ts

Open PR replacement branches

Existing PR	Existing branch	Replacement compare
#111	`issue-110-sqlite3-parser-schemadiff`	`improve-codebase-architecture-2026-05-14...improve-codebase-architecture-2026-05-14-pr-111`
#108	`typegen-casing`	`improve-codebase-architecture-2026-05-14...improve-codebase-architecture-2026-05-14-pr-108`
#101	`sql-runner-named-params-2026-05-12`	`improve-codebase-architecture-2026-05-14...improve-codebase-architecture-2026-05-14-pr-101`

Package size — packed 234.4 kB (+307 B, +0.1%)

Package size

	main	this PR	Δ
packed	234.1 kB	234.4 kB	+0.1%
unpacked	958.1 kB	960.5 kB	+0.3%
files	179	181	+2

`dist/vendor/*.js` bundles

	main	this PR
`vendor/sha256.js`	4.3 kB	4.3 kB
`vendor/sql-formatter/*.js`	58.3 kB	58.3 kB
`vendor/sqlfu-sqlite-parser/*.js`	17.2 kB	17.2 kB
`vendor/standard-schema/*.js`	2.8 kB	2.8 kB
`vendor/typesql/*.js`	134.6 kB	134.6 kB

Measured with npm pack --dry-run --json on sqlfu (0.0.3-7 on main vs 0.0.3-7 on this PR).

Note

Low Risk
Mostly an internal refactor that moves existing SQL parameter parsing/rewriting logic into query-parameters.ts with new unit tests; risk is limited to potential regressions in typegen parameter inference and analysis-SQL rewriting.

Overview
Extracts the query parameter parsing/expansion machinery (named-parameter scanning, inline expansion inference, comment/string masking, and analysis-SQL rewriting) out of typegen/index.ts into a new internal module typegen/query-parameters.ts, with index.ts now importing and using that API.

Adds focused Vitest coverage for findNamedParameterReferences, parseInlineParameterExpansions, and prepareSqlForAnalysis to ensure parameters are ignored inside comments/strings and that object/list-shaped params expand correctly for analysis without changing the runtime SQL source.

^{Reviewed by Cursor Bugbot for commit 4dbbf4e. Bugbot is set up for automated code reviews on this repo. Configure here.}

pkg-pr-new · 2026-05-14T15:38:04Z

Open in StackBlitz

npm i https://pkg.pr.new/sqlfu@113

commit: 4dbbf4e

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4dbbf4e. Configure here.}

cursor · 2026-05-14T15:54:27Z

+      chars[index] = ' ';
+    }
+  }
+  return chars.join('');


Duplicated maskSqlCommentsAndStrings across both modules

Low Severity

maskSqlCommentsAndStrings has an identical implementation in both index.ts and query-parameters.ts. Since index.ts already imports findSqlIgnoredRanges from query-parameters.ts (and maskSqlCommentsAndStrings is just a thin wrapper over it), the function could be exported from query-parameters.ts and imported in index.ts instead of being duplicated.

Additional Locations (1)

packages/sqlfu/src/typegen/query-parameters.ts#L439-L448

^{Reviewed by Cursor Bugbot for commit 4dbbf4e. Configure here.}

## Summary Completes the 2026-05-14 evergreen cleanup pass for task bookkeeping. The pass confirms PRs #113, #108, and #101 are already represented in `tasks/complete/` with completed checklist breadcrumbs, so no duplicate task moves are needed for those merges. It also files the stale active intro-blog task from merged PR #100 by moving it to `tasks/complete/2026-05-14-intro-blog.md` and marking the last checklist item with the merge breadcrumb. ## Reviewer effect After merge, the root `tasks/` folder no longer shows the already-landed intro blog work as active, and `tasks/cleanup-tasks.md` records exactly which recent merged PRs were audited and why the remaining local worktrees were left alone. Local cleanup performed outside the diff: removed eight clean worktree checkouts whose head branches corresponded to merged PRs (#101, #103, #104, #105, #106, #107, #108, #113). Branches were left intact. ## Verification - `gh pr view 113 --json number,title,state,mergedAt,mergeCommit,url` - `gh pr view 108 --json number,title,state,mergedAt,mergeCommit,url` - `gh pr view 101 --json number,title,state,mergedAt,mergeCommit,url` - `gh pr view 100 --json number,title,state,mergedAt,mergeCommit,url` - `rg --files tasks | sort | rg 'intro-blog|cleanup-tasks|2026-05-14'` - `git worktree list --porcelain` - `git status --short --branch`  --- > [!NOTE] > **Low Risk** > Low risk housekeeping-only changes to task documentation; no production code paths are modified. > > **Overview** > Updates the evergreen `tasks/cleanup-tasks.md` log with a completed 2026-05-14 pass, including notes on which merged PRs were already filed and which local merged worktrees were safely removed. > > Moves the stale merged `tasks/intro-blog.md` into `tasks/complete/2026-05-14-intro-blog.md`, marking it `status: done` and updating the final checklist item to reflect PR #100 being merged. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 3a216e0. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>   <details> <summary>Package size — packed 236.5 kB (no change)</summary> ## Package size | | main | this PR | Δ | | - | - | - | - | | packed | 236.5 kB | 236.5 kB | 0 | | unpacked | 971.3 kB | 971.3 kB | 0 | | files | 181 | 181 | 0 | ### `dist/vendor/*.js` bundles | | main | this PR | Δ | | - | - | - | - | | `vendor/sha256.js` | 4.3 kB | 4.3 kB | 0 | | `vendor/sql-formatter/*.js` | 58.3 kB | 58.3 kB | 0 | | `vendor/sqlfu-sqlite-parser/*.js` | 17.2 kB | 17.2 kB | 0 | | `vendor/standard-schema/*.js` | 2.8 kB | 2.8 kB | 0 | | `vendor/typesql/*.js` | 134.6 kB | 134.6 kB | 0 | _Measured with `npm pack --dry-run --json` on `sqlfu` (0.0.3-7 on main vs 0.0.3-7 on this PR)._ </details>

Specify query parameter expansion locality task

5d940b7

mmkal added 2 commits May 14, 2026 16:43

Extract query parameter expansion module

db668ed

Complete query parameter expansion locality task

4dbbf4e

mmkal marked this pull request as ready for review May 14, 2026 15:49

cursor Bot reviewed May 14, 2026

View reviewed changes

mmkal merged commit e5d560d into main May 14, 2026
9 checks passed

This was referenced May 14, 2026

Improve generated query parameter docs #115

Merged

File stale completed tasks from cleanup pass #116

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deepen query parameter expansion locality#113

Deepen query parameter expansion locality#113
mmkal merged 3 commits into
mainfrom
improve-codebase-architecture-2026-05-14

mmkal commented May 14, 2026 •

edited by cursor Bot

Loading

Uh oh!

pkg-pr-new Bot commented May 14, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mmkal commented May 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Verification

Open PR replacement branches

Package size

dist/vendor/*.js bundles

Uh oh!

pkg-pr-new Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 14, 2026

Choose a reason for hiding this comment

Duplicated maskSqlCommentsAndStrings across both modules

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mmkal commented May 14, 2026 •

edited by cursor Bot

Loading

`dist/vendor/*.js` bundles

pkg-pr-new Bot commented May 14, 2026 •

edited

Loading

Duplicated `maskSqlCommentsAndStrings` across both modules