Framework/Lua/Diagnostics/LuaSelfTest.cs

Self-test harness for the package's Lua runtime. Runs a large table of Lua snippets through a fresh LuaState and compares the returned string to an expected value, plus separate checks for syntax error reporting, instruction budget watchdog, host function binding, realm isolation, expression depth and nesting limits, and host exception containment. Returns a pass/fail summary for use from the editor.

using System;
using System.Collections.Generic;
using System.Text;

namespace RoleplayFramework.Lua.Diagnostics;

/// <summary>
/// Conformance and sandbox checks for the Lua runtime. Each case runs in a fresh state and
/// must return a string equal to the expected value. Run from the editor with run_csharp:
/// <c>return RoleplayFramework.Lua.Diagnostics.LuaSelfTest.RunAll();</c>
/// </summary>
public static class LuaSelfTest
{
	public sealed record Result( string Name, bool Passed, string Detail );

	public sealed record Summary( int Passed, int Failed, string Runtime, double Milliseconds, List<Result> Failures, string Report );

	static readonly (string name, string code, string expected)[] Cases =
	{
		// --- core semantics
		("arith", "return tostring(1+2*3-4/2) .. ' ' .. tostring(2^10) .. ' ' .. tostring(7 % 3) .. ' ' .. tostring(-7 % 3)", "5 1024 1 2"),
		("number format", "return tostring(10/4) .. ' ' .. tostring(1e20) .. ' ' .. tostring(100) .. ' ' .. tostring(0.1)", "2.5 1e+20 100 0.1"),
		("string coercion", "return tostring('10' + 5) .. ' ' .. (1 .. 2)", "15 12"),
		("precedence", "return tostring(2^3^2) .. ' ' .. tostring(-2^2) .. ' ' .. tostring(not nil == true)", "512 -4 true"),
		("concat right assoc", "return 'a' .. 'b' .. 'c' .. 1 .. 2", "abc12"),
		("and/or", "return tostring(nil or 'x') .. tostring(false and 1) .. tostring(1 and 2)", "xfalse2"),
		("comparison", "return tostring(1 < 2) .. tostring('a' < 'b') .. tostring(2 <= 2) .. tostring(3 ~= 3)", "truetruetruefalse"),
		("multiple assign", "local a, b, c = 1, 2; a, b = b, a; return a .. b .. tostring(c)", "21nil"),
		("varargs", "local function f(...) local a, b = ...; return select('#', ...), a, b end; local n, a, b = f(1, nil, 3); return n .. tostring(a) .. tostring(b)", "31nil"),
		("vararg table", "local function f(...) return {...} end; return #f(1,2,3,4)", "4"),
		("multret in middle", "local function f() return 1, 2 end; local t = {f(), f()}; return #t", "3"),
		("paren truncates", "local function f() return 1, 2 end; local t = {(f())}; return #t", "1"),
		("closures per iteration", "local fs = {}; for i = 1, 3 do fs[i] = function() return i end end; return fs[1]() .. fs[2]() .. fs[3]()", "123"),
		("upvalue sharing", "local function counter() local n = 0; return function() n = n + 1; return n end end; local c = counter(); c(); c(); return c()", "3"),
		("nested upvalues", "local x = 1; local function a() return function() return function() x = x + 1; return x end end end; a()()(); return a()()()", "3"),
		("recursion", "local function fib(n) if n < 2 then return n end return fib(n-1) + fib(n-2) end; return fib(20)", "6765"),
		("while/repeat", "local i, s = 0, 0; while i < 10 do i = i + 1; s = s + i end; repeat s = s - 1 local stop = s < 50 until stop; return s", "49"),
		("numeric for step", "local s = ''; for i = 10, 1, -3 do s = s .. i .. ',' end; return s", "10,7,4,1,"),
		("generic for pairs", "local t = {a=1, b=2, c=3}; local s = 0; for k, v in pairs(t) do s = s + v end; return s", "6"),
		("ipairs stops at nil", "local t = {1, 2, nil, 4}; local n = 0; for _, v in ipairs(t) do n = n + 1 end; return n", "2"),
		("pairs order array first", "local t = {10, 20, 30, x = 1}; local s = ''; for k in pairs(t) do s = s .. tostring(k) end; return s", "123x"),
		("clear during traversal", "local t = {}; for i = 1, 20 do t['k'..i] = i end; for k in pairs(t) do t[k] = nil end; return tostring(next(t))", "nil"),
		("length border", "local t = {}; t[1] = 1; t[2] = 2; t[3] = 3; t[3] = nil; return #t", "2"),
		("hash to array migration", "local t = {}; t[3] = 'c'; t[2] = 'b'; t[1] = 'a'; return #t .. table.concat(t)", "3abc"),
		("break", "local n = 0; for i = 1, 100 do if i > 5 then break end; n = i end; return n", "5"),
		("method call", "local obj = {v = 41}; function obj:inc() self.v = self.v + 1; return self.v end; return obj:inc()", "42"),
		("string methods", "local s = 'Hello'; return s:upper() .. s:len() .. ('x'):rep(3)", "HELLO5xxx"),
		("long strings", "local s = [[\nline1\nline2]]; local t = [==[a]]b]==]; return #s .. t", "11a]]b"),
		("escapes", "return '\\65\\066\\x43\\t|' .. #'\\n'", "ABC\t|1"),

		// --- GLua extensions
		("glua operators", "local a = 1; if a != 2 && !(a == 3) || false then return 'ok' end return 'bad'", "ok"),
		("glua comments", "local a = 1 // comment\n/* block\ncomment */ return a + 1", "2"),
		("continue", "local s = 0; for i = 1, 10 do if i % 2 == 0 then continue end; s = s + i end; return s", "25"),

		// --- metatables
		("__index table", "local base = {greet = function() return 'hi' end}; local o = setmetatable({}, {__index = base}); return o.greet()", "hi"),
		("__index function", "local o = setmetatable({}, {__index = function(t, k) return k .. '!' end}); return o.foo", "foo!"),
		("__newindex", "local log = {}; local o = setmetatable({}, {__newindex = function(t, k, v) rawset(t, k, v * 2) end}); o.x = 5; return o.x", "10"),
		("__call", "local o = setmetatable({}, {__call = function(self, a, b) return a + b end}); return o(2, 3)", "5"),
		("__add/__eq/__lt", "local mt = {}; mt.__add = function(a, b) return setmetatable({v = a.v + b.v}, mt) end; mt.__eq = function(a, b) return a.v == b.v end; mt.__lt = function(a, b) return a.v < b.v end; local function V(v) return setmetatable({v = v}, mt) end; return tostring((V(1) + V(2)) == V(3)) .. tostring(V(1) < V(2)) .. tostring(V(2) <= V(1))", "truetruefalse"),
		("__tostring", "return tostring(setmetatable({}, {__tostring = function() return 'OBJ' end}))", "OBJ"),
		("__concat/__len/__unm", "local mt = {__concat = function(a, b) return 'cat' end, __len = function() return 99 end, __unm = function() return 'neg' end}; local o = setmetatable({}, mt); return (o .. 'x') .. #o .. (-o)", "cat99neg"),
		("protected metatable", "local o = setmetatable({}, {__metatable = 'locked'}); local ok = pcall(setmetatable, o, {}); return tostring(getmetatable(o)) .. tostring(ok)", "lockedfalse"),

		// --- errors
		("pcall error string", "local ok, e = pcall(function() error('boom') end); return tostring(ok) .. ' ' .. e", "false test:1: boom"),
		("pcall error level 0", "local ok, e = pcall(error, 'raw', 0); return e", "raw"),
		("pcall error table", "local ok, e = pcall(error, {code = 7}); return e.code", "7"),
		("runtime error position", "local ok, e = pcall(function()\nlocal t = nil\nreturn t.x\nend); return e", "test:3: attempt to index local 't' (a nil value)"),
		("call nil global", "local ok, e = pcall(function() undefined_fn() end); return e", "test:1: attempt to call global 'undefined_fn' (a nil value)"),
		("arith error", "local ok, e = pcall(function() return {} + 1 end); return e", "test:1: attempt to perform arithmetic on a table value"),
		("compare error", "local ok, e = pcall(function() return {} < 1 end); return e", "test:1: attempt to compare table with number"),
		("xpcall handler", "local ok, e = xpcall(function() error('x', 0) end, function(m) return 'handled:' .. m end); return e", "handled:x"),
		("assert", "local ok, e = pcall(assert, false, 'nope'); return e .. tostring(select(2, pcall(assert, 1, 2)))", "nope1"),
		("bad argument", "local ok, e = pcall(string.rep); return e", "bad argument #1 to 'rep' (string expected, got no value)"),
		("error rethrow keeps value", "local ok, e = pcall(function() local ok2, e2 = pcall(error, 'inner', 0); error(e2, 0) end); return e", "inner"),

		// --- string library
		("string.sub", "local s = 'abcdef'; return s:sub(2, 4) .. s:sub(-2) .. s:sub(5, 100) .. s:sub(0)", "bcdefefabcdef"),
		("string.byte/char", "return string.char(string.byte('ABC', 1, 3)) .. string.byte('a')", "ABC97"),
		("string.find plain", "return table.concat({string.find('a.b.c', '.', 1, true)}, ',')", "2,2"),
		("string.find pattern", "return table.concat({string.find('hello world', 'o w')}, ',') .. '|' .. table.concat({('key=value'):find('(%w+)=(%w+)')}, ',')", "5,7|1,9,key,value"),
		("string.match", "return string.match('  trim me  ', '^%s*(.-)%s*$') .. '|' .. string.match('2024-11-18', '(%d+)-(%d+)')", "trim me|2024"),
		("string.match anchors/classes", "return tostring(('abc'):match('^b')) .. ('x=1, y=22'):match('y=(%d+)') .. ('[tag]'):match('%[(%a+)%]')", "nil22tag"),
		("string.gmatch", "local t = {}; for k, v in string.gmatch('a=1, b=2, c=3', '(%w+)=(%w+)') do t[#t+1] = k .. v end; return table.concat(t, ' ')", "a1 b2 c3"),
		("string.gsub string", "return (string.gsub('hello world', 'o', '0')) .. select(2, string.gsub('aaa', 'a', 'b'))", "hell0 w0rld3"),
		("string.gsub captures", "return (string.gsub('John Smith', '(%w+) (%w+)', '%2, %1'))", "Smith, John"),
		("string.gsub function/table", "local r = string.gsub('$name is $age', '%$(%w+)', {name = 'Bob', age = 30}); local r2 = string.gsub('abc', '%w', function(c) return c:upper() .. '.' end); return r .. '|' .. r2", "Bob is 30|A.B.C."),
		("string.gsub limit/anchor", "return (string.gsub('aaaa', 'a', 'b', 2)) .. (string.gsub('aaaa', '^a', 'b'))", "bbaabaaa"),
		("pattern %b and %f", "return ('f(a(b)c)d'):match('%b()') .. '|' .. (string.gsub('THE (quick) fox', '%f[%a]%a+', 'W'))", "(a(b)c)|W (W) W"),
		("pattern back reference", "return ('say \"hi\" now'):match('([\"\\'])(.-)%1')", "\""),
		("pattern position capture", "return table.concat({('hello'):match('()ll()')}, ',')", "3,5"),
		("pattern sets", "return (string.gsub('a1-b2_c3', '[^%a]', '')) .. (string.gsub('abcxyz', '[a-c]', '*'))", "abc***xyz"),
		("string.format ints", "return string.format('%d|%5d|%-5d|%05d|%+d|%x|%X|%o', 42, 42, 42, 42, 42, 255, 255, 8)", "42|   42|42   |00042|+42|ff|FF|10"),
		("string.format floats", "return string.format('%.2f|%10.3f|%e|%g|%g|%g', 3.14159, 2.5, 12345.678, 0.0001, 1e20, 100)", "3.14|     2.500|1.234568e+04|0.0001|1e+20|100"),
		("string.format strings", "return string.format('%s|%10s|%-4s|%.2s|%q|%%|%c', 'x', 'right', 'l', 'abc', 'a\"b', 65)", "x|     right|l   |ab|\"a\\\"b\"|%|A"),
		("string.format tostring", "return string.format('%s %s %s', nil, true, setmetatable({}, {__tostring = function() return 'T' end}))", "nil true T"),

		// --- table / math / misc
		("table.insert/remove", "local t = {1, 2, 3}; table.insert(t, 4); table.insert(t, 1, 0); local r = table.remove(t, 2); local last = table.remove(t); return table.concat(t, ',') .. '|' .. r .. last", "0,2,3|14"),
		("table.sort", "local t = {5, 2, 8, 1, 9}; table.sort(t); local u = {'b', 'c', 'a'}; table.sort(u, function(a, b) return a > b end); return table.concat(t, ',') .. '|' .. table.concat(u)", "1,2,5,8,9|cba"),
		("table.sort stable records", "local t = {{n='a', v=2}, {n='b', v=1}, {n='c', v=2}}; table.sort(t, function(x, y) return x.v < y.v end); return t[1].n .. t[2].n .. t[3].n", "bac"),
		("unpack", "return select('#', unpack({1, 2, 3})) .. table.concat({unpack({1, 2, 3}, 2)})", "323"),
		("tonumber", "return tostring(tonumber('0x1F')) .. tostring(tonumber(' 12 ')) .. tostring(tonumber('ff', 16)) .. tostring(tonumber('z'))", "3112255nil"),
		("math", "return math.floor(3.7) .. math.ceil(3.2) .. math.max(1, 5, 3) .. math.min(4, 2) .. math.abs(-3) .. math.fmod(7, 3)", "345231"),
		("math.random range", "math.randomseed(1); for i = 1, 200 do local r = math.random(1, 6); if r < 1 or r > 6 or r % 1 ~= 0 then return 'bad' end end; return 'ok'", "ok"),
		("type", "return type(nil) .. type(1) .. type('') .. type({}) .. type(print) .. type(true)", "nilnumberstringtablefunctionboolean"),
		("_G", "x_global = 5; return _G.x_global + _G['x_global']", "10"),
		("os.time", "return type(os.time()) .. type(os.clock()) .. type(os.date('%Y'))", "numbernumberstring"),

		// --- clearing fields during traversal is allowed in Lua (GMod's table.Empty does it)
		("clear array during pairs", "local t = { 1, 2, 3 } for k in pairs(t) do t[k] = nil end return tostring(next(t))", "nil"),
		("clear mixed table during pairs", "local t = { 1, 2, a = 1, b = 2 } local n = 0 for k in pairs(t) do t[k] = nil n = n + 1 end return n .. tostring(next(t))", "4nil"),

		// --- sandbox: none of these may exist
		("sandbox: no io/debug/package", "return tostring(io) .. tostring(debug) .. tostring(package) .. tostring(require)", "nilnilnilnil"),
		("sandbox: no dynamic code loading", "return tostring(load) .. tostring(loadstring) .. tostring(dofile) .. tostring(loadfile)", "nilnilnilnil"),
		("sandbox: no os escape hatches", "return tostring(os.execute) .. tostring(os.remove) .. tostring(os.rename) .. tostring(os.getenv) .. tostring(os.exit)", "nilnilnilnilnil"),
		("sandbox: no env manipulation", "return tostring(setfenv) .. tostring(getfenv) .. tostring(collectgarbage) .. tostring(newproxy)", "nilnilnilnil"),
		("stack overflow is catchable", "local function f() return f() + 1 end; local ok, e = pcall(f); return tostring(ok) .. tostring(e:find('stack overflow') ~= nil)", "falsetrue"),
	};

	public static Summary RunAll()
	{
		var start = DateTime.UtcNow;
		var results = new List<Result>();

		foreach ( var (name, code, expected) in Cases )
			results.Add( RunCase( name, code, expected ) );

		results.Add( CheckSyntaxError() );
		results.Add( CheckBudget() );
		results.Add( CheckBudgetNotCatchable() );
		results.Add( CheckHostBinding() );
		results.Add( CheckRealmIsolation() );
		results.Add( CheckHostExceptionContained() );
		results.Add( CheckExpressionDepthLimit() );
		results.Add( CheckNestingLimit() );

		var ms = (DateTime.UtcNow - start).TotalMilliseconds;
		var failures = results.FindAll( r => !r.Passed );
		int passed = results.Count - failures.Count;

		var sb = new StringBuilder();
		sb.Append( $"{LuaState.RuntimeName} {LuaState.RuntimeVersion} ({LuaState.LanguageVersion}): {passed}/{results.Count} passed in {ms:F1} ms" );
		foreach ( var f in failures ) sb.Append( $"\n  FAIL {f.Name}: {f.Detail}" );

		return new Summary( passed, failures.Count, $"{LuaState.RuntimeName} {LuaState.RuntimeVersion}", ms, failures, sb.ToString() );
	}

	static Result RunCase( string name, string code, string expected )
	{
		try
		{
			var L = new LuaState( "selftest" );
			var r = L.DoString( code, "test" );
			var got = r.Length > 0 ? r[0].ToString() : "<no value>";
			return got == expected
				? new Result( name, true, null )
				: new Result( name, false, $"expected [{expected}] got [{got}]" );
		}
		catch ( LuaRuntimeException e )
		{
			return new Result( name, false, $"runtime error: {e.Message}\n{e.LuaTraceback}" );
		}
		catch ( Exception e )
		{
			return new Result( name, false, $"{e.GetType().Name}: {e.Message}" );
		}
	}

	static Result CheckSyntaxError()
	{
		const string name = "syntax error reports chunk and line";
		try
		{
			new LuaState().Load( "local a = 1\nlocal b = = 2", "gamemodes/darkrp/sv_init.lua" );
			return new Result( name, false, "no error raised" );
		}
		catch ( LuaSyntaxException e )
		{
			bool ok = e.ChunkName == "gamemodes/darkrp/sv_init.lua" && e.Line == 2 && e.Message.StartsWith( "gamemodes/darkrp/sv_init.lua:2:" );
			return new Result( name, ok, e.Message );
		}
	}

	static Result CheckBudget()
	{
		const string name = "instruction budget stops infinite loop";
		var L = new LuaState { InstructionBudget = 100_000 };
		try
		{
			L.DoString( "while true do end", "loop" );
			return new Result( name, false, "loop was not stopped" );
		}
		catch ( LuaBudgetExceededException e )
		{
			// The state must be reusable after the watchdog fires.
			var r = L.DoString( "return 1 + 1", "after" );
			return new Result( name, r[0].Number == 2, e.Message );
		}
	}

	static Result CheckBudgetNotCatchable()
	{
		const string name = "pcall cannot swallow the budget watchdog";
		var L = new LuaState { InstructionBudget = 100_000 };
		try
		{
			L.DoString( "while true do pcall(function() while true do end end) end", "trap" );
			return new Result( name, false, "loop was not stopped" );
		}
		catch ( LuaBudgetExceededException )
		{
			return new Result( name, true, null );
		}
	}

	static Result CheckHostBinding()
	{
		const string name = "host functions and callbacks";
		var L = new LuaState();
		var hooks = new Dictionary<string, LuaValue>();
		var hook = L.GetOrCreateLibrary( "hook" );
		LuaState.Register( hook, "Add", ( s, a ) =>
		{
			hooks[LuaState.CheckString( a, 0, "hook.Add" )] = a[1];
			return null;
		} );

		L.DoString( "hook.Add('PlayerSpawn', function(name, money) return name .. ' spawned with $' .. money end)", "sh_init.lua" );
		var r = L.PCall( hooks["PlayerSpawn"], "Alice", 500 );
		return new Result( name, r.Success && r.Results[0].AsString == "Alice spawned with $500", r.Error ?? r.Results[0].AsString );
	}

	static Result CheckRealmIsolation()
	{
		const string name = "realms are isolated";
		var server = new LuaState( "server" );
		var client = new LuaState( "client" );
		server.DoString( "SECRET = 'server only'", "sv_secret.lua" );
		var r = client.DoString( "return tostring(SECRET)", "cl_probe.lua" );
		return new Result( name, r[0].AsString == "nil", r[0].AsString );
	}

	static Result CheckExpressionDepthLimit()
	{
		const string name = "huge expression chain is rejected, not a crash";
		var sb = new StringBuilder( "return 1" );
		for ( int i = 0; i < 5000; i++ ) sb.Append( " + 1" );
		try
		{
			new LuaState().Load( sb.ToString(), "chain" );
			return new Result( name, false, "no error raised" );
		}
		catch ( LuaSyntaxException e )
		{
			return new Result( name, e.Message.Contains( "expression too complex" ), e.Message );
		}
	}

	static Result CheckNestingLimit()
	{
		const string name = "deep nesting is rejected, not a crash";
		var src = new string( '(', 5000 ) + "1" + new string( ')', 5000 );
		try
		{
			new LuaState().Load( "return " + src, "nest" );
			return new Result( name, false, "no error raised" );
		}
		catch ( LuaSyntaxException e )
		{
			return new Result( name, e.Message.Contains( "too many syntax levels" ), e.Message );
		}
	}

	static Result CheckHostExceptionContained()
	{
		const string name = "host exceptions become Lua errors";
		var L = new LuaState();
		L.Register( "explode", ( s, a ) => throw new InvalidOperationException( "host bug" ) );
		var r = L.DoString( "local ok, e = pcall(explode); return e", "probe" );
		var got = r[0].AsString ?? "";
		return new Result( name, got.Contains( "internal error in 'explode'" ), got );
	}
}