Skip to content

feat: emit func_name caller-symbol tag (#3422)#17

Merged
veksen merged 2 commits into
masterfrom
feat-func-name-tag
Jun 30, 2026
Merged

feat: emit func_name caller-symbol tag (#3422)#17
veksen merged 2 commits into
masterfrom
feat-func-name-tag

Conversation

@veksen

@veksen veksen commented Jun 30, 2026

Copy link
Copy Markdown
Member

Implements the producer half of Query-Doctor/Site#3422: capture the enclosing caller symbol from the same V8 stack frame traceCaller() already parses, and emit it as a new func_name SQLCommenter tag.

Why

Provenance today is file:line:col only. Line/col drift when code above the call site changes, so mapping captured queries back to source against any other revision silently misattributes them (Query-Doctor/Site#3367). The enclosing method symbol (e.g. reactionsRepo.findFavorites) is edit-stable and is the join key that makes captured-query → source-method coverage mapping (Query-Doctor/Site#3418 / Query-Doctor/Site#3419) reliable without checking out the capture's exact commit. func_name is the canonical key other adapters (postgres-tracked-pool) already emit.

What changed

  • traceCaller() now returns { file, symbol? } instead of a bare file string. The symbol is parsed from the same frame already selected — no new frame-selection logic.
  • New func_name tag emitted when a symbol is present; falls back to file alone when the frame is anonymous / <anonymous> / top-level (never an empty tag). async prefixes are stripped.
  • In drizzle, the { file, symbol? } payload is threaded through the 0.4.0 per-query concurrency machinery unchanged — only the payload widened from string.
  • Applied to drizzle, mikroorm, and typeorm; each README's emitted-fields table gains the func_name row.

Verification (grounded in real V8 frames, not assumptions)

Probed actual frames first, then asserted:

  • named function → loadRow; object method → Object.findFavorites; class method → UserService.list; arrow-assigned const → arrowAssigned.
  • anonymous frame → no func_name, file still emitted (the fallback contract).
  • concurrency → two queries built before either executes each keep their own symbol.
  • serialization: keys sort alphabetically (db_driver, file, func_name, …); asserted file precedes func_name.

All suites pass: drizzle 26, mikroorm 31, typeorm 24 (dual ESM/CJS builds clean).

Versions

  • drizzle 0.4.0 → 0.5.0, mikroorm 0.3.0 → 0.4.0, typeorm 0.3.0 → 0.4.0 (new emitted tag; traceCaller's return shape changed, so a minor under 0.x).

Refs: Query-Doctor/Site#3422, Query-Doctor/Site#3367, Query-Doctor/Site#3418, Query-Doctor/Site#3419. The Site consumer (feat-caller-symbol-tag) already renders func_name, so it displays the moment this publishes.

🤖 Generated with Claude Code

veksen and others added 2 commits June 30, 2026 16:10
`traceCaller()` already parses the V8 frame that holds the enclosing
function/method symbol (e.g. `UserService.list`, `reactionsRepo.findFavorites`)
— it was discarded by the regex that keeps only `path:line:col`. Capture it and
emit it as a new `func_name` SQLCommenter tag.

Unlike `file:line:col`, a symbol is edit-stable: it doesn't drift when code
above the call site changes, which makes captured-query → source-method mapping
reliable across revisions. `func_name` is the shared join key other adapters
(e.g. postgres-tracked-pool) already emit.

Capture-when-present, fall back to `file` alone: anonymous / `<anonymous>` /
top-level frames (and minified builds) emit `file` only, never an empty tag.
`traceCaller()` now returns `{ file, symbol? }`, threaded through the 0.4.0
per-query concurrency machinery unchanged — only the payload widened from a
string. Applied to drizzle, mikroorm, and typeorm; READMEs gain the row.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- @query-doctor/sqlcommenter-drizzle: 0.4.0 -> 0.5.0
- @query-doctor/sqlcommenter-mikroorm: 0.3.0 -> 0.4.0
- @query-doctor/sqlcommenter-typeorm: 0.3.0 -> 0.4.0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@veksen veksen merged commit 8b1a30a into master Jun 30, 2026
4 checks passed
@veksen veksen deleted the feat-func-name-tag branch July 1, 2026 00:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant