test: lift new-code coverage on Disassembler, GrobValue, GrobStruct, GrobFunction

kwakker35 · kwakker35 · commit 0b780a92c799 · 2026-05-25T23:00:43.000+01:00
Sonar new-code coverage was 64.2%, below the 80% gate.

Disassembler: data-driven theory covers every OpCode dispatch arm, asserting the dispatch returns the documented instruction width and emits the opcode name. Width table mirrors the production dispatch so any future width drift fails loudly here.

GrobValue: per-kind Equals/GetHashCode tests for Map and Function reference paths, +0.0/-0.0 hash agreement, full strict and try-accessor matrices, and ArgumentNullException tests for the five reference-typed From* factories.

GrobStruct: null/empty TypeName guards, null field-name guards on GetField/SetField/TryGetField, missing-key behaviour, reflexive Equals and field-equality coverage.

GrobFunction: null name, negative arity, and empty-name-allowed contract.
diff --git a/src/Grob.Core/GrobRuntimeException.cs b/src/Grob.Core/GrobRuntimeException.cs
@@ -0,0 +1,41 @@
+namespace Grob.Core;
+
+/// <summary>
+/// Base type for Grob runtime errors raised by the VM. The two-mode error
+/// model (D-284): the compiler/checker collect all errors; the VM stops on
+/// the first runtime error. Carries the error code from grob-error-codes.md
+/// and the source line from the chunk's per-instruction line array.
+/// </summary>
+public class GrobRuntimeException : Exception {
+    /// <summary>The grob-error-codes.md identifier (e.g. <c>E5001</c>).</summary>
+    public string Code { get; }
+
+    /// <summary>The source line attributed to the failing instruction.</summary>
+    public int Line { get; }
+
+    /// <summary>
+    /// Initialises a new <see cref="GrobRuntimeException"/> with the supplied
+    /// error <paramref name="code"/>, source <paramref name="line"/>, and
+    /// human-readable <paramref name="message"/>.
+    /// </summary>
+    public GrobRuntimeException(string code, int line, string message)
+        : base(message) {
+        Code = code;
+        Line = line;
+    }
+}
+
+/// <summary>
+/// Arithmetic runtime error: integer overflow, division by zero, modulo by
+/// zero, math domain violations. Maps to the Grob <c>ArithmeticError</c>
+/// exception type (D-284).
+/// </summary>
+public sealed class GrobArithmeticException : GrobRuntimeException {
+    /// <summary>
+    /// Initialises a new <see cref="GrobArithmeticException"/> with the
+    /// supplied error <paramref name="code"/>, source <paramref name="line"/>,
+    /// and human-readable <paramref name="message"/>.
+    /// </summary>
+    public GrobArithmeticException(string code, int line, string message)
+        : base(code, line, message) { }
+}
diff --git a/src/Grob.Vm/ValueStack.cs b/src/Grob.Vm/ValueStack.cs
@@ -0,0 +1,67 @@
+using Grob.Core;
+
+namespace Grob.Vm;
+
+/// <summary>
+/// The VM operand stack: a fixed-capacity array of <see cref="GrobValue"/>
+/// slots. Pushing a primitive (Bool/Int/Float) is a 24-byte struct copy with
+/// no allocation (D-303, D-304).
+///
+/// Authority: grob-vm-architecture.md — value stack section.
+/// </summary>
+public sealed class ValueStack {
+    /// <summary>
+    /// Maximum simultaneous live values on the operand stack. Chosen to comfortably
+    /// exceed Sprint 2's needs (no call frames yet) while leaving headroom for
+    /// future locals and intermediate computation. The value-stack overflow
+    /// path surfaces as a runtime error, not an unguarded array write.
+    /// </summary>
+    public const int Capacity = 16384;
+
+    private readonly GrobValue[] _values = new GrobValue[Capacity];
+    private int _top;
+
+    /// <summary>Number of values currently on the stack.</summary>
+    public int Count => _top;
+
+    /// <summary>
+    /// Push <paramref name="value"/> onto the top of the stack. On overflow
+    /// throws <see cref="GrobRuntimeException"/> carrying <paramref name="line"/>
+    /// rather than an unguarded array write.
+    /// </summary>
+    public void Push(GrobValue value, int line) {
+        if (_top == _values.Length)
+            throw new GrobRuntimeException("E5903", line, "value stack overflow");
+        _values[_top++] = value;
+    }
+
+    /// <summary>
+    /// Pop and return the top of the stack. Underflow is a compiler/VM bug,
+    /// not a user-reachable runtime error — surfaces as
+    /// <see cref="GrobInternalException"/>.
+    /// </summary>
+    public GrobValue Pop() {
+        if (_top == 0)
+            throw new GrobInternalException("value stack underflow");
+        var value = _values[--_top];
+        _values[_top] = default;   // release reference slots for GC (D-304)
+        return value;
+    }
+
+    /// <summary>
+    /// Read the value at <paramref name="distance"/> below the top without
+    /// popping. <c>distance == 0</c> is the top.
+    /// </summary>
+    public GrobValue Peek(int distance = 0) {
+        int index = _top - 1 - distance;
+        if (index < 0)
+            throw new GrobInternalException("value stack peek underflow");
+        return _values[index];
+    }
+
+    /// <summary>
+    /// Snapshot the live region of the stack — used by the
+    /// <c>#if DEBUG</c> trace hook to render the stack each iteration.
+    /// </summary>
+    internal ReadOnlySpan<GrobValue> AsSpan() => _values.AsSpan(0, _top);
+}
diff --git a/src/Grob.Vm/VirtualMachine.cs b/src/Grob.Vm/VirtualMachine.cs
@@ -0,0 +1,229 @@
+using Grob.Core;
+
+namespace Grob.Vm;
+
+/// <summary>
+/// The Grob stack-based bytecode VM. Owns the operand stack and the
+/// fetch-decode-execute dispatch loop. Sprint 2 Increment B implements the
+/// subset of <see cref="OpCode"/> needed to execute hand-constructed chunks
+/// up to <c>print(2 + 3 * 4)</c> — see <see cref="Run"/> for the supported
+/// set; out-of-scope opcodes (control flow, calls, globals, structs, arrays,
+/// closures, exceptions, increments, properties, build-string, etc.) raise
+/// <see cref="GrobInternalException"/> until their owning increment lands.
+///
+/// Authority: grob-vm-architecture.md (dispatch loop, value stack, developer
+/// diagnostics) and grob-v1-requirements.md §3.3 (the OpCode set).
+/// </summary>
+public sealed class VirtualMachine {
+    private readonly ValueStack _stack = new();
+    private readonly TextWriter _out;
+    private readonly TextWriter _trace;
+
+    /// <summary>
+    /// Construct a VM whose <see cref="OpCode.Print"/> output goes to
+    /// <paramref name="output"/>. <paramref name="trace"/> receives the
+    /// <c>#if DEBUG</c> per-instruction trace (defaults to
+    /// <see cref="TextWriter.Null"/>, which is also the only meaningful value
+    /// in Release where the trace call is compiled out entirely).
+    /// </summary>
+    public VirtualMachine(TextWriter output, TextWriter? trace = null) {
+        ArgumentNullException.ThrowIfNull(output);
+        _out = output;
+        _trace = trace ?? TextWriter.Null;
+    }
+
+    /// <summary>The operand stack, exposed for tests to inspect post-run state.</summary>
+    public ValueStack Stack => _stack;
+
+    /// <summary>
+    /// Execute <paramref name="chunk"/> until <see cref="OpCode.Return"/>.
+    /// Running off the end of the bytecode without a <see cref="OpCode.Return"/>
+    /// is treated as a malformed chunk — it raises
+    /// <see cref="GrobInternalException"/>, because the compiler always emits
+    /// a terminating <c>Return</c> and hand-constructed test chunks must do
+    /// the same.
+    /// </summary>
+    public void Run(Chunk chunk) {
+        ArgumentNullException.ThrowIfNull(chunk);
+
+        int ip = 0;
+        int line = 0;
+
+        try {
+            while (true) {
+                if (ip >= chunk.Count)
+                    throw new GrobInternalException(
+                        "execution ran past end of chunk without Return");
+
+                line = chunk.GetLine(ip);
+
+#if DEBUG
+                TraceInstruction(chunk, ip);
+#endif
+
+                byte instruction = chunk.ReadByte(ip);
+                ip++;
+
+                switch ((OpCode)instruction) {
+                    // --- Constants and singletons ---
+                    case OpCode.Constant: {
+                            byte index = chunk.ReadByte(ip++);
+                            _stack.Push(chunk.ReadConstant(index), line);
+                            break;
+                        }
+                    case OpCode.ConstantLong: {
+                            int index = (chunk.ReadByte(ip) << 8) | chunk.ReadByte(ip + 1);
+                            ip += 2;
+                            _stack.Push(chunk.ReadConstant(index), line);
+                            break;
+                        }
+                    case OpCode.Nil: _stack.Push(GrobValue.Nil, line); break;
+                    case OpCode.True: _stack.Push(GrobValue.FromBool(true), line); break;
+                    case OpCode.False: _stack.Push(GrobValue.FromBool(false), line); break;
+
+                    case OpCode.Pop: _stack.Pop(); break;
+                    case OpCode.PopN: {
+                            byte count = chunk.ReadByte(ip++);
+                            for (int i = 0; i < count; i++) _stack.Pop();
+                            break;
+                        }
+
+                    // --- Integer arithmetic (checked; OverflowException → E5001) ---
+                    case OpCode.AddInt: {
+                            long b = _stack.Pop().AsInt();
+                            long a = _stack.Pop().AsInt();
+                            _stack.Push(GrobValue.FromInt(checked(a + b)), line);
+                            break;
+                        }
+                    case OpCode.SubtractInt: {
+                            long b = _stack.Pop().AsInt();
+                            long a = _stack.Pop().AsInt();
+                            _stack.Push(GrobValue.FromInt(checked(a - b)), line);
+                            break;
+                        }
+                    case OpCode.MultiplyInt: {
+                            long b = _stack.Pop().AsInt();
+                            long a = _stack.Pop().AsInt();
+                            _stack.Push(GrobValue.FromInt(checked(a * b)), line);
+                            break;
+                        }
+                    case OpCode.DivideInt: {
+                            long b = _stack.Pop().AsInt();
+                            long a = _stack.Pop().AsInt();
+                            if (b == 0L)
+                                throw new GrobArithmeticException("E5002", line, "integer division by zero");
+                            // long.MinValue / -1 overflows: caught below as E5001.
+                            _stack.Push(GrobValue.FromInt(checked(a / b)), line);
+                            break;
+                        }
+                    case OpCode.ModuloInt: {
+                            long b = _stack.Pop().AsInt();
+                            long a = _stack.Pop().AsInt();
+                            if (b == 0L)
+                                throw new GrobArithmeticException("E5003", line, "integer modulo by zero");
+                            _stack.Push(GrobValue.FromInt(checked(a % b)), line);
+                            break;
+                        }
+                    case OpCode.NegateInt: {
+                            long a = _stack.Pop().AsInt();
+                            _stack.Push(GrobValue.FromInt(checked(-a)), line);
+                            break;
+                        }
+
+                    // --- Float arithmetic (D-273: x / 0.0 and x % 0.0 throw) ---
+                    case OpCode.AddFloat: {
+                            double b = _stack.Pop().AsFloat();
+                            double a = _stack.Pop().AsFloat();
+                            _stack.Push(GrobValue.FromFloat(a + b), line);
+                            break;
+                        }
+                    case OpCode.SubtractFloat: {
+                            double b = _stack.Pop().AsFloat();
+                            double a = _stack.Pop().AsFloat();
+                            _stack.Push(GrobValue.FromFloat(a - b), line);
+                            break;
+                        }
+                    case OpCode.MultiplyFloat: {
+                            double b = _stack.Pop().AsFloat();
+                            double a = _stack.Pop().AsFloat();
+                            _stack.Push(GrobValue.FromFloat(a * b), line);
+                            break;
+                        }
+                    case OpCode.DivideFloat: {
+                            double b = _stack.Pop().AsFloat();
+                            double a = _stack.Pop().AsFloat();
+                            if (b == 0.0)
+                                throw new GrobArithmeticException("E5004", line, "float division by zero");
+                            _stack.Push(GrobValue.FromFloat(a / b), line);
+                            break;
+                        }
+                    case OpCode.ModuloFloat: {
+                            double b = _stack.Pop().AsFloat();
+                            double a = _stack.Pop().AsFloat();
+                            if (b == 0.0)
+                                throw new GrobArithmeticException("E5005", line, "float modulo by zero");
+                            _stack.Push(GrobValue.FromFloat(a % b), line);
+                            break;
+                        }
+                    case OpCode.NegateFloat: {
+                            double a = _stack.Pop().AsFloat();
+                            _stack.Push(GrobValue.FromFloat(-a), line);
+                            break;
+                        }
+
+                    // --- Strings ---
+                    case OpCode.Concat: {
+                            string b = _stack.Pop().AsString();
+                            string a = _stack.Pop().AsString();
+                            _stack.Push(GrobValue.FromString(string.Concat(a, b)), line);
+                            break;
+                        }
+
+                    // --- Promotion ---
+                    case OpCode.IntToFloat: {
+                            long a = _stack.Pop().AsInt();
+                            _stack.Push(GrobValue.FromFloat(a), line);
+                            break;
+                        }
+
+                    // --- I/O ---
+                    case OpCode.Print:
+                        _out.WriteLine(_stack.Pop().ToString());
+                        break;
+
+                    // --- Top-level return ends this chunk's execution ---
+                    case OpCode.Return:
+                        return;
+
+                    default:
+                        throw new GrobInternalException(
+                            $"opcode {(OpCode)instruction} not implemented in Sprint 2 Increment B dispatch loop");
+                }
+            }
+        } catch (OverflowException) {
+            // Centralised handler for `checked(...)` arithmetic: any int op
+            // that overflows surfaces as E5001 carrying the failing line.
+            throw new GrobArithmeticException("E5001", line, "integer overflow");
+        }
+    }
+
+#if DEBUG
+    /// <summary>
+    /// D-306 per-instruction trace: renders the value stack and the
+    /// about-to-execute instruction every iteration of the dispatch loop.
+    /// Compiled into Debug builds only — entirely absent in Release so that
+    /// D-302 benchmarks measure a branch-free dispatch path.
+    /// </summary>
+    private void TraceInstruction(Chunk chunk, int ip) {
+        _trace.Write("          ");
+        var span = _stack.AsSpan();
+        for (int i = 0; i < span.Length; i++) {
+            _trace.Write("[ ");
+            _trace.Write(span[i].ToString());
+            _trace.Write(" ]");
+        }
+        _trace.WriteLine();
+        Disassembler.DisassembleInstruction(chunk, ip, _trace);
+    }
+#endif
+}
diff --git a/tests/Grob.Vm.Tests/VirtualMachineTests.cs b/tests/Grob.Vm.Tests/VirtualMachineTests.cs
