Add bare T-SQL RETURN for batch-level early-exit (propagates through IF / BEGIN…END / WHILE via BatchContext.ReturnSignaled; value-form raises Msg 178 at compile time, deferred until stored-proc / function scope lands).

RyanLamansky · RyanLamansky · commit 1dfc04544ff6 · 2026-05-11T09:03:39.000-05:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -337,8 +337,8 @@ Creates a destination table from the projection's inferred schema, then copies r
 - **INTO without FROM** works (`SELECT 1 AS x INTO #t`) — synthesized-row path threads `IntoTarget` through.
 - **Quirk**: CTE-wrapped single-heap source drops identity and nullability — the simulator's CTE bindings synthesize `HeapColumn` entries with `nullable: true` and no identity, so the analyzer can't peer through. Real SQL Server propagates both. Fix would require propagating column metadata through CTE bindings; future bundle.
 
-### T-SQL control flow: `IF` / `BEGIN…END` / `WHILE` / `BREAK` / `CONTINUE`
-`IF <boolean-expr> <stmt> [ELSE <stmt>]`, `BEGIN <stmt>+ END` compound blocks, `WHILE <boolean-expr> <stmt>` loops with `BREAK` / `CONTINUE`. GOTO/labels and TRY/CATCH still aren't modeled. Probed against SQL Server 2025 (2026-05-11).
+### T-SQL control flow: `IF` / `BEGIN…END` / `WHILE` / `BREAK` / `CONTINUE` / `RETURN`
+`IF <boolean-expr> <stmt> [ELSE <stmt>]`, `BEGIN <stmt>+ END` compound blocks, `WHILE <boolean-expr> <stmt>` loops with `BREAK` / `CONTINUE`, bare `RETURN` for batch-level early-exit. GOTO/labels, TRY/CATCH, and the value-form `RETURN N` (stored-proc / function scope) still aren't modeled. Probed against SQL Server 2025 (2026-05-11).
 
 - **Body grammar**: exactly one statement. The famous T-SQL footgun `IF cond SELECT 'a' SELECT 'b'` runs *both* SELECTs — only the first is the IF body; the second escapes the IF as a subsequent batch-level statement. Replicated.
 - **Dangling-else binds to the inner IF** (standard rule). `IF 1=0 IF 1=1 stmt ELSE stmt` → outer skips the entire inner-IF including its ELSE; no output.
@@ -358,11 +358,15 @@ Creates a destination table from the projection's inferred schema, then copies r
 
 **`LoopDepth` is bumped unconditionally** (even when the WHILE itself is in skip mode) so BREAK / CONTINUE inside the body — including inside un-taken IF branches — never see Msg 135 / 136 fire incorrectly. The flag-write gate (`!IsSkipping`) handles the runtime "BREAK in skipped-IF inside WHILE" case.
 
-**Un-taken-branch skip mode** (`BatchContext.SkipModeFlag` + `IsSkipping` computed property). The IF parser sets `SkipModeFlag` around dispatch of the un-taken branch (THEN if cond false, ELSE if cond true), then restores in a `finally`. `IsSkipping = SkipModeFlag || LoopControl != None` is the combined predicate every statement parser reads. Skip-mode propagates through nested IF/BEGIN/WHILE automatically — a nested IF inside a skipped block reads `IsSkipping=true`, short-circuits cond eval entirely (so a divide-by-zero inside un-evaluated cond doesn't fire), and dispatches both its branches in skip mode. A WHILE in skip mode never iterates; it skip-dispatches its body once to advance the cursor and exits.
+**`RETURN` — bare-form only, batch-exit propagation.** Set `BatchContext.ReturnSignaled = true` (gated on `!IsSkipping`); `IsSkipping` OR's it in, and the dispatch loop's `DispatchStatementsUntil` checks the flag at the top of every iteration to `yield break`. The WHILE iteration loop checks after every body dispatch (RETURN propagates *through* WHILE — only `BREAK` / `CONTINUE` are caught by the innermost loop). `ParseBeginBlock` short-circuits its "expect END" check when the flag is set, since RETURN may fire mid-block before the cursor reaches END. End result: bare RETURN exits the entire batch — through any nesting of IF / BEGIN…END / WHILE — and any code after it (including `SELECT 'after'` follow-ups or unreached `END` terminators) never executes.
+
+**`RETURN <value>` raises Msg 178** verbatim (`"A RETURN statement with a return value cannot be used in this context."`) at parse time, regardless of skip mode — the value form is reserved for stored procedures and scalar functions, neither of which is modeled yet. Compile-time check (same pattern as BREAK Msg 135): `IF 1=0 RETURN 5` raises Msg 178 even though the branch is un-taken. The simulator detects "value follows" via `IsStatementBoundary(context.Token)` — any non-boundary token after RETURN (operators, variables, literals, parens, non-statement-start keywords) triggers Msg 178; boundary tokens (`;`, EOB, statement-start keywords like SELECT/INSERT/IF/etc.) leave RETURN bare.
+
+**Un-taken-branch skip mode** (`BatchContext.SkipModeFlag` + `IsSkipping` computed property). The IF parser sets `SkipModeFlag` around dispatch of the un-taken branch (THEN if cond false, ELSE if cond true), then restores in a `finally`. `IsSkipping = SkipModeFlag || LoopControl != None || ReturnSignaled` is the combined predicate every statement parser reads. Skip-mode propagates through nested IF/BEGIN/WHILE automatically — a nested IF inside a skipped block reads `IsSkipping=true`, short-circuits cond eval entirely (so a divide-by-zero inside un-evaluated cond doesn't fire), and dispatches both its branches in skip mode. A WHILE in skip mode never iterates; it skip-dispatches its body once to advance the cursor and exits.
 
 Each statement parser still runs its full parse — the cursor advances normally, names resolve, expressions parse — but gates its state mutation on `!batch.IsSkipping`. Touchpoints: SELECT `Execute` call in the dispatch, `ProcessHeapInsert`'s heap insert + `LastIdentity` update, `CommitUpdate`'s heap delete+insert, `CommitDelete`'s heap delete, MERGE's INSERT branch, `TryParseCreate`'s dict add + Msg 2714 existence check, `DropOneTable`'s lookup + Msg 3701 + dict remove, `ExecuteSelectInto`'s create + bulk-insert, `TryParseSetVariable`'s `slot.Value =` (plus its RHS evaluation), `TryParseSetIdentityInsert`'s state change, `TryParseDeclare`'s dict add + Msg 134 duplicate check + initializer evaluation, `TryParseBeginTransaction` / `TryParseCommit` / `TryParseRollbackTransaction` / `TryParseSavepoint`'s state changes (including their no-active-tx error checks), `TryParseAlter`'s database property write, `TryParseDbcc`'s trace-flag mutation. The dispatch loop also suppresses `yield return` for SELECT results and the `LastStatementRowCount` update on skipped statements.
 
-**Dispatch refactor**: extracted `DispatchOneStatement(batch, requireSemicolonBeforeCte)` and `DispatchStatementsUntil(batch, endKeyword)` from `CreateResultSetsForCommand`. The top-level loop calls `DispatchStatementsUntil(null)`; `ParseBeginBlock` calls `DispatchStatementsUntil(Keyword.End)`; `ParseIfStatement` and `ParseWhileStatement` call `DispatchOneStatement` directly (the body of each is exactly one statement). `IsStatementBoundary` includes `If` / `Else` / `End` / `While` / `Break` / `Continue` so the cursor-normalization at the end of each dispatch correctly recognizes nested-control terminators. `Selection.ParseInner`'s projection-list terminator switch lists the same set plus `Drop` so `SELECT ... ELSE` / `SELECT ... END` / `SELECT ... BREAK` / etc. correctly stop at the keyword instead of throwing Msg 102.
+**Dispatch refactor**: extracted `DispatchOneStatement(batch, requireSemicolonBeforeCte)` and `DispatchStatementsUntil(batch, endKeyword)` from `CreateResultSetsForCommand`. The top-level loop calls `DispatchStatementsUntil(null)`; `ParseBeginBlock` calls `DispatchStatementsUntil(Keyword.End)`; `ParseIfStatement` and `ParseWhileStatement` call `DispatchOneStatement` directly (the body of each is exactly one statement). `IsStatementBoundary` includes `If` / `Else` / `End` / `While` / `Break` / `Continue` / `Return` so the cursor-normalization at the end of each dispatch correctly recognizes nested-control terminators. `Selection.ParseInner`'s projection-list terminator switch lists the same set plus `Drop` so `SELECT ... ELSE` / `SELECT ... END` / `SELECT ... BREAK` / etc. correctly stop at the keyword instead of throwing Msg 102.
 
 **Fidelity gap** (Q15): real SQL Server defers name resolution for un-taken branches — `IF 1=0 SELECT bad_col FROM bad_table` runs silently. The simulator's parsers do name resolution inline with parsing, so un-taken branches with non-existent table/column refs still raise Msg 208 / Msg 207. Common idioms (safe-CREATE / safe-DROP / safe-INSERT against pre-existing tables) work end-to-end because referenced names exist when the branch is skipped.
 
@@ -409,8 +413,8 @@ Full `DbDataReader` contract. Typed accessors read `SqlValue` directly via the c
 - **Global temp tables (`##foo`)** — `NotSupportedException` at parse. Local `#foo` works; the lifecycle for global temps (drops when creator session closes, visible across sessions) is the deferred scope.
 - **`ALTER TABLE #foo`**, **`TRUNCATE TABLE #foo`**, **`OBJECT_ID('tempdb..#foo')`** — none modeled (none of those exist for regular tables either yet). The common `IF OBJECT_ID(...) IS NOT NULL DROP TABLE` cleanup pattern works via `DROP TABLE IF EXISTS #foo` instead.
 - **Three-part name resolution outside DROP TABLE**: `tempdb..#foo` in FROM / INSERT / UPDATE / DELETE / MERGE / SET IDENTITY_INSERT raises `InvalidObjectName` (Msg 208) on the qualifier; use bare `#foo`. DROP TABLE alone tolerates the qualifier (probe pattern).
-- T-SQL `GOTO` / labels — `IF` / `BEGIN…END` / `WHILE` / `BREAK` / `CONTINUE` ship; unconditional jumps don't.
-- `TRY ... CATCH`, `THROW`, `RAISERROR`, `@@ERROR`, `RETURN`, `PRINT`, stored procs / UDFs. `BEGIN TRY` / `BEGIN ATOMIC` / `BEGIN DISTRIBUTED TRANSACTION` raise `NotSupportedException` at dispatch (peeked after `BEGIN`).
+- T-SQL `GOTO` / labels — `IF` / `BEGIN…END` / `WHILE` / `BREAK` / `CONTINUE` / `RETURN` (bare) ship; unconditional jumps don't.
+- `TRY ... CATCH`, `THROW`, `RAISERROR`, `@@ERROR`, `PRINT`, stored procs / UDFs. `BEGIN TRY` / `BEGIN ATOMIC` / `BEGIN DISTRIBUTED TRANSACTION` raise `NotSupportedException` at dispatch (peeked after `BEGIN`). Value-form `RETURN N` raises Msg 178 (reserved for the stored-proc / function scope, neither modeled yet).
 - `hierarchyid`, `geography`, `geometry`.
 
 ## Quirks (modeled, not byte-identical to SQL Server)
diff --git a/SqlServerSimulator.Tests/ReturnStatementTests.cs b/SqlServerSimulator.Tests/ReturnStatementTests.cs
@@ -0,0 +1,174 @@
+using static Microsoft.VisualStudio.TestTools.UnitTesting.Assert;
+
+namespace SqlServerSimulator;
+
+/// <summary>
+/// Tests for the bare <c>RETURN</c> statement (the value-form
+/// <c>RETURN N</c> is reserved for stored procedures / functions, neither
+/// of which is modeled — value form always raises Msg 178). Covers
+/// batch-exit semantics, propagation through IF / BEGIN…END / WHILE,
+/// the compile-time Msg 178 check (fires even in un-taken IF, same
+/// pattern as BREAK Msg 135), and skip-mode interactions. Behavior
+/// probed against SQL Server 2025 (2026-05-11).
+/// </summary>
+[TestClass]
+public sealed class ReturnStatementTests
+{
+    [TestMethod]
+    public void BareReturn_ExitsBatch()
+    {
+        using var reader = new Simulation().ExecuteReader("select 'before'; return; select 'after'");
+        IsTrue(reader.Read());
+        AreEqual("before", reader.GetString(0));
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    [TestMethod]
+    public void BareReturn_AtEndOfBatch_Clean()
+    {
+        // ExecuteNonQuery returns -1 when no DML / DDL ran; the assertion
+        // is just that the batch completed without throwing.
+        _ = new Simulation().ExecuteNonQuery("return");
+    }
+
+    [TestMethod]
+    public void ReturnInTakenIf_ExitsBatch()
+    {
+        using var reader = new Simulation().ExecuteReader("if 1=1 return; select 'after'");
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    [TestMethod]
+    public void ReturnInUntakenIf_StatementAfterRuns()
+        => AreEqual("after", new Simulation().ExecuteScalar(
+            "if 1=0 return; select 'after'"));
+
+    [TestMethod]
+    public void ReturnInElseBranch_ExitsBatch()
+    {
+        using var reader = new Simulation().ExecuteReader(
+            "if 1=0 select 'then' else return; select 'after'");
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    /// <summary>
+    /// Probe-confirmed: RETURN inside a WHILE exits the entire batch, not
+    /// just the loop (unlike BREAK).
+    /// </summary>
+    [TestMethod]
+    public void ReturnInWhile_ExitsBatchNotJustLoop()
+    {
+        using var reader = new Simulation().ExecuteReader("""
+            declare @i int = 0;
+            while @i < 100
+            begin
+                set @i = @i + 1;
+                if @i = 3 return;
+            end;
+            select 'after'
+            """);
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    [TestMethod]
+    public void ReturnInNestedWhile_ExitsAllLoops()
+    {
+        using var reader = new Simulation().ExecuteReader("""
+            while 1=1
+            begin
+                while 1=1
+                begin
+                    return;
+                end;
+            end;
+            select 'after'
+            """);
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    [TestMethod]
+    public void ReturnInBlock_SkipsSiblings()
+    {
+        using var reader = new Simulation().ExecuteReader("""
+            begin
+                select 'a';
+                return;
+                select 'b';
+            end;
+            select 'after'
+            """);
+        IsTrue(reader.Read());
+        AreEqual("a", reader.GetString(0));
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    [TestMethod]
+    public void MultipleReturn_FirstWins()
+    {
+        _ = new Simulation().ExecuteNonQuery("return; return; return");
+    }
+
+    /// <summary>
+    /// Bare RETURN followed by a statement-starting keyword is bare RETURN
+    /// — the SELECT begins a new statement (which gets abandoned because
+    /// the batch is exiting). Probe-confirmed against SQL Server 2025.
+    /// </summary>
+    [TestMethod]
+    public void ReturnFollowedByStatementKeyword_IsBareReturn()
+    {
+        // SELECT 1 never runs (batch exits via RETURN); we just verify the
+        // batch parses + completes without throwing Msg 178.
+        using var reader = new Simulation().ExecuteReader("return select 1");
+        IsFalse(reader.Read());
+        IsFalse(reader.NextResult());
+    }
+
+    // ---- Msg 178: value-form RETURN ----
+
+    [TestMethod]
+    public void ReturnInteger_Msg178()
+        => new Simulation().AssertSqlError("return 5", 178,
+            "A RETURN statement with a return value cannot be used in this context.");
+
+    [TestMethod]
+    public void ReturnZero_Msg178()
+        => new Simulation().AssertSqlError("return 0", 178);
+
+    [TestMethod]
+    public void ReturnNull_Msg178()
+        => new Simulation().AssertSqlError("return null", 178);
+
+    [TestMethod]
+    public void ReturnString_Msg178()
+        => new Simulation().AssertSqlError("return 'abc'", 178);
+
+    [TestMethod]
+    public void ReturnVariable_Msg178()
+        => new Simulation().AssertSqlError("declare @v int = 7; return @v", 178);
+
+    [TestMethod]
+    public void ReturnExpression_Msg178()
+        => new Simulation().AssertSqlError("return (1+2)", 178);
+
+    [TestMethod]
+    public void ReturnParenWrapped_Msg178()
+        => new Simulation().AssertSqlError("return(1)", 178);
+
+    /// <summary>
+    /// Compile-time check: Msg 178 fires even when the RETURN is in an
+    /// un-taken IF branch. Probe-confirmed — same semantics as BREAK Msg 135.
+    /// </summary>
+    [TestMethod]
+    public void ReturnValueInUntakenIf_StillMsg178()
+        => new Simulation().AssertSqlError("if 1=0 return 5", 178);
+
+    [TestMethod]
+    public void ReturnValueInUntakenIf_BeforeFollowingStmt_StillMsg178()
+        => new Simulation().AssertSqlError("if 1=0 return 5; select 'ok'", 178);
+}
diff --git a/SqlServerSimulator/Errors/SimulatedSqlException.SyntaxErrors.cs b/SqlServerSimulator/Errors/SimulatedSqlException.SyntaxErrors.cs
@@ -115,4 +115,16 @@ internal static SimulatedSqlException BreakOutsideLoop() =>
     /// </summary>
     internal static SimulatedSqlException ContinueOutsideLoop() =>
         new("Cannot use a CONTINUE statement outside the scope of a WHILE statement.", 136, 15, 1);
+
+    /// <summary>
+    /// Mimics SQL Server error 178: a <c>RETURN</c> statement carries a
+    /// value (e.g. <c>RETURN 5</c>) in a context where the value form isn't
+    /// allowed — at batch level, only the bare <c>RETURN</c> form is legal.
+    /// The value form is reserved for stored procedures and scalar functions.
+    /// Probe-confirmed against SQL Server 2025 (2026-05-11): Class 15,
+    /// State 1, exact wording verbatim. Fires at compile time — even from
+    /// un-taken IF branches, same pattern as Msg 135 (BREAK).
+    /// </summary>
+    internal static SimulatedSqlException ReturnWithValueNotAllowed() =>
+        new("A RETURN statement with a return value cannot be used in this context.", 178, 15, 1);
 }
diff --git a/SqlServerSimulator/Parser/BatchContext.cs b/SqlServerSimulator/Parser/BatchContext.cs
@@ -81,6 +81,23 @@ internal sealed class BatchContext
     /// <summary>Per-batch ceiling on total WHILE iterations.</summary>
     public const long LoopIterationLimit = 100_000;
 
+    /// <summary>
+    /// True after a <c>RETURN</c> statement has fired in this batch. Drives
+    /// early-exit propagation: the dispatch loop (and every enclosing
+    /// construct — WHILE, BEGIN…END block) checks this and stops as soon as
+    /// the current statement's dispatch completes. <see cref="IsSkipping"/>
+    /// also OR's this in so any statements still parsed after RETURN in the
+    /// same scope no-op via the skip-mode gates.
+    /// </summary>
+    /// <remarks>
+    /// RETURN propagates through WHILE (unlike BREAK / CONTINUE, which the
+    /// innermost WHILE catches). Batch-level only for now; once stored
+    /// procedures and functions land, the proc-call boundary will consume
+    /// the signal (and the value-form <c>RETURN N</c> will start being legal
+    /// inside those scopes, ungating the Msg 178 check).
+    /// </remarks>
+    public bool ReturnSignaled;
+
     /// <summary>
     /// True while the dispatch loop should treat each statement parser as
     /// "parse only" — advance the cursor and resolve names but skip the
@@ -110,7 +127,10 @@ internal sealed class BatchContext
     /// compile-time check on those statements.
     /// </para>
     /// </remarks>
-    public bool IsSkipping => this.SkipModeFlag || this.LoopControl != LoopControl.None;
+    public bool IsSkipping =>
+        this.SkipModeFlag
+        || this.LoopControl != LoopControl.None
+        || this.ReturnSignaled;
 
     /// <summary>The connection executing this batch.</summary>
     public SimulatedDbConnection Connection => this.Parser.Connection;
diff --git a/SqlServerSimulator/Parser/Selection.cs b/SqlServerSimulator/Parser/Selection.cs
@@ -422,7 +422,7 @@ private static Selection ParseInner(ParserContext context, uint depth, List<Aggr
                         or Keyword.Merge or Keyword.Begin or Keyword.Commit or Keyword.Rollback
                         or Keyword.Save or Keyword.Create or Keyword.Drop or Keyword.Alter or Keyword.Dbcc
                         or Keyword.Set or Keyword.Declare or Keyword.If or Keyword.Else or Keyword.End
-                        or Keyword.While or Keyword.Break or Keyword.Continue
+                        or Keyword.While or Keyword.Break or Keyword.Continue or Keyword.Return
                 } when depth == 0:
                     goto ExitWhileTokenLoop;
 
@@ -565,7 +565,7 @@ or Keyword.While or Keyword.Break or Keyword.Continue
                         or Keyword.Merge or Keyword.Begin or Keyword.Commit or Keyword.Rollback
                         or Keyword.Save or Keyword.Create or Keyword.Drop or Keyword.Alter or Keyword.Dbcc
                         or Keyword.Set or Keyword.Declare or Keyword.If or Keyword.Else or Keyword.End
-                        or Keyword.While or Keyword.Break or Keyword.Continue
+                        or Keyword.While or Keyword.Break or Keyword.Continue or Keyword.Return
                 } when depth == 0:
                     goto ExitWhileTokenLoop;
 
diff --git a/SqlServerSimulator/Simulation/Simulation.IfBlock.cs b/SqlServerSimulator/Simulation/Simulation.IfBlock.cs
diff --git a/SqlServerSimulator/Simulation/Simulation.cs b/SqlServerSimulator/Simulation/Simulation.cs
