feat: hoist mid-statement comments above their enclosing statement

Comments like 'SELECT id, -- note' that fall inside a statement's
byte range are detected and repositioned above the statement rather
than trailing at the end. New fixture mid-statement-comments.sql
documents this behavior with snapshots.

68 total tests, 8 snapshots.

Author: pyramation

packages/parse/__tests__/__snapshots__/roundtrip.test.ts.snap

@@ -75,6 +75,46 @@ GRANT SELECT ON app.users TO authenticated;
 GRANT ALL ON app.users TO admin_role;"
 `;
 
+exports[`fixture round-trip (CST) mid-statement-comments deparsed output matches snapshot 1`] = `
+"-- Mid-statement comments are hoisted above their enclosing statement.
+-- The deparser cannot inject comments back into the middle of a
+-- statement, so they are preserved as standalone lines above it.
+
+-- Simple mid-statement comment
+-- the primary key
+SELECT
+  id,
+  name
+FROM users;
+
+-- Multiple mid-statement comments in one query
+-- user ID
+-- display name
+-- role from join
+SELECT
+  u.id,
+  u.name,
+  r.role_name
+FROM users AS u
+JOIN roles AS r ON r.id = u.role_id;
+
+-- Mid-statement comment in INSERT values
+-- log level
+-- log body
+INSERT INTO logs (
+  level,
+  message
+) VALUES
+  ('info', 'hello');
+
+-- Comment between clauses
+-- filter active only
+SELECT id
+FROM users
+WHERE
+  active = true;"
+`;
+
 exports[`fixture round-trip (CST) multi-statement deparsed output matches snapshot 1`] = `
 "-- Schema setup
 CREATE SCHEMA IF NOT EXISTS app;

packages/parse/__tests__/fixtures/mid-statement-comments.sql

@@ -0,0 +1,30 @@
+-- Mid-statement comments are hoisted above their enclosing statement.
+-- The deparser cannot inject comments back into the middle of a
+-- statement, so they are preserved as standalone lines above it.
+
+-- Simple mid-statement comment
+SELECT
+  id, -- the primary key
+  name
+FROM users;
+
+-- Multiple mid-statement comments in one query
+SELECT
+  u.id,       -- user ID
+  u.name,     -- display name
+  r.role_name -- role from join
+FROM users u
+JOIN roles r ON r.id = u.role_id;
+
+-- Mid-statement comment in INSERT values
+INSERT INTO logs (level, message)
+VALUES (
+  'info', -- log level
+  'hello' -- log body
+);
+
+-- Comment between clauses
+SELECT id
+FROM users
+-- filter active only
+WHERE active = true;

packages/parse/src/parse.ts

@@ -66,26 +66,64 @@ function findActualSqlStart(
  * because stmt_location can include preceding whitespace/comments,
  * making a simple merge unreliable.
  */
+/**
+ * Build a list of statement byte ranges (actualStart … end) so we can
+ * detect mid-statement comments and hoist them above their enclosing
+ * statement instead of leaving them trailing at the wrong position.
+ */
+interface StmtRange {
+  actualStart: number;
+  end: number; // stmt_location + stmt_len, or sql.length for last stmt
+}
+
+function buildStmtRanges(
+  stmts: RawStmt[],
+  sql: string,
+  elements: ScannedElement[]
+): StmtRange[] {
+  return stmts.map(stmt => {
+    const loc = stmt.stmt_location ?? 0;
+    const actualStart = findActualSqlStart(sql, loc, elements);
+    const len = stmt.stmt_len ?? sql.length - loc;
+    return { actualStart, end: loc + len };
+  });
+}
+
 function interleave(
   parseResult: ParseResult,
   sql: string,
   elements: ScannedElement[]
 ): EnhancedParseResult {
   const stmts = parseResult.stmts ?? [];
   const items: SortableEntry[] = [];
+  const ranges = buildStmtRanges(stmts, sql, elements);
 
   // Add scanned elements (comments and whitespace)
   for (const elem of elements) {
     if (elem.kind === 'comment') {
+      // Check if this comment falls inside a statement's byte range.
+      // If so, hoist it above that statement instead of leaving it
+      // at its original position (which would place it after the
+      // statement or trailing at the wrong spot).
+      let hoistedPosition: number | null = null;
+      for (const range of ranges) {
+        if (elem.value.start > range.actualStart && elem.value.start < range.end) {
+          hoistedPosition = range.actualStart;
+          break;
+        }
+      }
+
       items.push({
-        position: elem.value.start,
+        position: hoistedPosition ?? elem.value.start,
         priority: 0,
         entry: {
           RawComment: {
             type: elem.value.type,
             text: elem.value.text,
             location: elem.value.start,
-            ...(elem.value.trailing ? { trailing: true } : {}),
+            // Only preserve trailing flag when NOT hoisted —
+            // a hoisted comment becomes a standalone line above the statement.
+            ...(hoistedPosition == null && elem.value.trailing ? { trailing: true } : {}),
           }
         }
       });
@@ -104,13 +142,11 @@ function interleave(
   }
 
   // Add parsed statements with their actual SQL start position
-  for (const stmt of stmts) {
-    const loc = stmt.stmt_location ?? 0;
-    const actualStart = findActualSqlStart(sql, loc, elements);
+  for (let i = 0; i < stmts.length; i++) {
     items.push({
-      position: actualStart,
+      position: ranges[i].actualStart,
       priority: 2, // statements sort after comments and whitespace
-      entry: stmt,
+      entry: stmts[i],
     });
   }