feat: end each statement with a comment naming its file - #43

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Reviewed changes

I reviewed the opt-in sqlcommenter key end to end: the engine config, the comment builder, the build-step module, the type check's declaration and the docs.

• Config key: sqlcommenter: Option<bool> on the engine's Project, with all three engine.wasm files rebuilt. resolveProject defaults it to false.
• withSqlcommenter: adds /*file='…'*/ before any closing semicolon. After a -- or # on the last line, the tag goes on a new line. encodeURIComponent encodes /, ?, : and $, so the tag can't contain */ or a placeholder. tests/sqlcommenter.test.ts passes locally.
• sourceName: the query's source now comes from the file's own project. This matches the old relative(session.project.root, path), because Session.for resolves from packageDir(dirname(path)) too.
• Loader and mapper: the module's sql/text and the declared sql literal both carry the tag. Structured-list offsets are still correct, because the tag only adds text at the end. The mapper's configIdentity includes the new flag.
• Docs: the key is in the Configuration example and has its own section.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

✅ No new issues found. Both must-fix items and the nit from the previous review are fixed.

Reviewed changes

This run covered 7ca1cdd, the one commit pushed since the previous review.

• Session cache key: Session.for now adds project.sqlcommenter to its cache key. If the project file turns the key on or off, the next module gets a new session, so the module's sql matches what the mapper declares. A session left behind this way closes its connection after BUILD_IDLE, the same as when url changes today.
• Test: tests/compiled.test.ts no longer closes sessions before the second build. It now tests the real case: a running build step picking up the change without a restart.
• Docs and comments: removed the Cloud SQL Query Insights claim from the Configuration section and the src/sqlcommenter.ts header.
• Loader: moved the structured-offsets comment back above the structured line.

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

✅ No new issues found. The branch was squashed and reworked so the comment is always on; I re-read the full diff.

Reviewed changes

The force-push to d991d85 removed the opt-in setting. Every built statement now gets the comment.

• Removed the sqlcommenter key: the engine config change, the rebuilt engine.wasm files, the Session.for cache-key change and the Configuration docs section are all gone. With no setting, a running build and the type check can't disagree about whether the comment is there.
• Kept withSqlcommenter as it was: trailing whitespace and ; are trimmed, the tag goes before a closing ;, and after a -- or # on the last line it starts a new line. The compiled text no longer ends with a newline, and the tests now expect that. tests/sqlcommenter.test.ts passes locally on Node 24.
• Made the declared sql match the module: the mapper now computes sourceName(p.fileName) from the file's own project, the same way the loader does. The sql doc comment shows the text without the tag, since a doc comment can't contain */. source is still typed as string.
• Updated the docs capture: site/scripts/capture-types.ts follows the mapper, using the block's name as the source, and sql-modules.json was recaptured. 02-usage.mdx gained one sentence and SQL_NOTE now mentions the ending comment.

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}