@hautajoki/hexagon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hautajoki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# Hexagon
+
+Hexagon is a Luau and Roblox test/benchmark runner. One package contains:
+
+- the `hexagon` Bun CLI;
+- the dependency-free Luau runtime and native runner;
+- a Roblox runner bundled into exact Tessera artifacts on demand;
+- TypeScript types for TypeScript-Go-Roblox suites.
+
+It is intentionally a testing tool, not a task runner. Tessera remains
+responsible for project configuration, builds, saved place versions,
+credentials, and Open Cloud execution.
+
+## Install
+
+During local development in this repository:
+
+```json
+{
+	"devDependencies": {
+		"@hautajoki/hexagon": "workspace:*"
+	}
+}
+```
+
+A packaged consumer installs the release as a normal development dependency
+and exposes direct scripts:
+
+```bash
+bun add --dev @hautajoki/hexagon
+```
+
+```json
+{
+	"scripts": {
+		"test": "hexagon test",
+		"bench": "hexagon bench"
+	}
+}
+```
+
+No second Hexagon config file is required.
+
+Native runs require the `luau` executable. Cloud runs additionally require the
+`tessera` executable at version 0.2.0 or newer and an existing Tessera
+project/place configuration.
+Hexagon owns the transient `<root>/test/hexagon` path; add that path to the
+project ignore file so an interrupted run cannot surface generated runtime
+files as authored changes.
+
+## Conventions
+
+- `*.local.spec.luau` and `*.local.bench.luau` are native-capable and also run
+  in cloud coverage.
+- `*.spec.ts`, `*.bench.ts`, `*.spec.luau`, and `*.bench.luau` run in a Roblox
+  Open Cloud artifact.
+- Suites return or default-export `(t) => { ... }`.
+- Files are discovered in lexical order.
+- Correctness tests in benchmark modules always run before timings.
+- Empty selections and focused `.only` cases exit nonzero by default.
+
+TypeScript suites import only the API type:
+
+```ts
+import type { Suite } from "@hautajoki/hexagon";
+
+const suite: Suite = (t) => {
+	t.test("works", () => {
+		const resource = acquireResource();
+		t.cleanup(() => resource.Destroy());
+		t.expect(resource).toExist();
+	});
+};
+
+export = suite;
+```
+
+Every `t.cleanup` callback runs once in LIFO order, even when the body or
+another cleanup fails. `afterEach` callbacks receive the same all-cleanups
+guarantee. Benchmark `afterSample` also runs when setup or timing fails, and a
+cleanup failure is retained alongside the primary failure.
+
+## Isolation
+
+File isolation is the default:
+
+- native files run in separate `luau` processes and therefore separate VMs;
+- cloud files run in separate Open Cloud executions and therefore separate
+  DataModels.
+
+Cases within one file intentionally share that file's VM/DataModel. Use
+`t.cleanup` for case-owned state. `--isolation run` is a faster opt-in that
+loads all selected files in one VM/DataModel.
+
+For cloud file isolation, Hexagon asks Tessera to build and save once, reads
+the exact version from `tessera run --json`, then invokes every suite against
+that same version.
+
+For native execution, Hexagon temporarily materializes its runtime under
+`<root>/test/hexagon` as well. This keeps Luau's relative module resolution
+inside the consumer source tree even when the package manager stores Hexagon in
+an external cache.
+
+## Open Cloud artifact bundling
+
+`hexagon test --cloud` temporarily materializes its version-matched Roblox
+runtime under `<root>/test/hexagon`, invokes `tessera run --fresh`, and removes
+the generated runtime afterward. The project keeps its normal
+`tessera.config.ts`; no generated suite manifest or second deployment config is
+committed.
+
+Co-located suites are compiled by the project's existing source/build recipe,
+so the saved test artifact contains both suites and the runner. This includes
+native-capable `.local.*` suites. A custom source router can override the runner
+DataModel path with `--runner`.
+
+This mechanism does not decide whether a project's production build excludes
+co-located suites. That remains an explicit build/release choice; use a
+dedicated test artifact or a project build variant when production exclusion is
+required.
+
+## Commands
+
+```bash
+hexagon test
+hexagon bench terrain
+hexagon test --cloud
+hexagon test --cloud --environment development --place main
+hexagon test --cloud --version 1234
+hexagon test --cloud --isolation run
+hexagon test --json
+```
+
+Fresh exact artifacts are the cloud default. `--published` is deliberately
+named for its weaker mutable-head semantics and is permitted only with shared
+run isolation. `--allow-focused` likewise requires `--isolation run`, ensuring
+that focus is global rather than scoped independently to each file. It is
+intended for a deliberate interactive run, not release validation.

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@hautajoki/hexagon",
+	"version": "0.1.0",
+	"description": "Luau and Roblox test/benchmark runner with exact-version Tessera execution",
+	"type": "module",
+	"license": "MIT",
+	"author": "hautajoki",
+	"bin": {
+		"hexagon": "src/cli.ts"
+	},
+	"types": "./types.d.ts",
+	"exports": {
+		".": {
+			"types": "./types.d.ts"
+		}
+	},
+	"files": [
+		"src",
+		"runtime",
+		"types.d.ts",
+		"README.md",
+		"LICENSE"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "bun test && bun run src/cli.ts test --root test",
+		"typecheck": "tsc -p tsconfig.json"
+	},
+	"devDependencies": {
+		"@types/bun": "1.3.14",
+		"typescript": "5.5.3"
+	},
+	"engines": {
+		"bun": ">=1.2.0"
+	},
+	"keywords": [
+		"roblox",
+		"luau",
+		"testing",
+		"benchmark",
+		"tessera"
+	]
+}

package/runtime/cloud_runner.luau

@@ -0,0 +1,139 @@
+--!strict
+-- Roblox Open Cloud entry point materialized into the consumer's test artifact.
+
+local hexagon = require("./hexagon")
+
+type InstanceLike = {
+	Name: string,
+	GetChildren: (self: InstanceLike) -> { InstanceLike },
+	GetFullName: (self: InstanceLike) -> string,
+	IsA: (self: InstanceLike, class_name: string) -> boolean,
+}
+
+type DataModelLike = InstanceLike & {
+	GetService: (self: DataModelLike, name: string) -> any,
+}
+
+type HttpServiceLike = {
+	JSONEncode: (self: HttpServiceLike, value: unknown) -> string,
+}
+
+type TaskSchedulerLike = {
+	wait: (duration: number?) -> number,
+}
+
+local data_model = (game :: any) :: DataModelLike
+local HttpService = data_model:GetService("HttpService") :: HttpServiceLike
+local require_module: (InstanceLike) -> unknown = require :: any
+local task_scheduler = (task :: any) :: TaskSchedulerLike
+
+local CASES_PER_YIELD = 16
+local MAX_SECONDS_WITHOUT_YIELD = 0.1
+
+export type RunRequest = {
+	mode: ("test" | "bench" | "all")?,
+	filter: string?,
+	suite: string?,
+}
+
+local PRUNE = {
+	node_modules = true,
+	rbxts_include = true,
+	_Index = true,
+}
+
+local function matches(module_script: InstanceLike, mode: string): boolean
+	if mode == "test" then return module_script.Name:match("%.spec$") ~= nil end
+	if mode == "bench" then return module_script.Name:match("%.bench$") ~= nil end
+	return module_script.Name:match("%.spec$") ~= nil or module_script.Name:match("%.bench$") ~= nil
+end
+
+local function discover(mode: string): { InstanceLike }
+	local modules: { InstanceLike } = {}
+	local function walk(parent: InstanceLike)
+		for _, child in parent:GetChildren() do
+			if PRUNE[child.Name] then continue end
+			if child:IsA("ModuleScript") and matches(child, mode) then table.insert(modules, child) end
+			walk(child)
+		end
+	end
+	walk(data_model)
+	table.sort(modules, function(left: InstanceLike, right: InstanceLike)
+		return left:GetFullName() < right:GetFullName()
+	end)
+	return modules
+end
+
+local module = {}
+
+function module.run(request: RunRequest?): string
+	local options: RunRequest = request or ({} :: RunRequest)
+	local mode: "test" | "bench" | "all" = options.mode or "all"
+	local modules = discover(mode)
+	if options.suite ~= nil then
+		local selected: { InstanceLike } = {}
+		for _, module_script in modules do
+			if module_script:GetFullName() == options.suite then table.insert(selected, module_script) end
+		end
+		if #selected == 0 then error(`suite not found in artifact: {options.suite}`, 0) end
+		modules = selected
+	end
+	local collection = hexagon.collect(function(t)
+		for _, module_script in modules do
+			t.describe(module_script:GetFullName(), function()
+				local loaded, exported = pcall(require_module, module_script)
+				if not loaded then
+					t.test("loads suite", function()
+						error(exported, 0)
+					end)
+					return
+				end
+
+				local suite: unknown = exported
+				if type(exported) == "table" then suite = (exported :: { default: unknown }).default end
+				if type(suite) ~= "function" then
+					t.test("loads suite", function()
+						error("suite module must return a function", 0)
+					end)
+					return
+				end
+
+				local registered, message = pcall(function(): unknown
+					(suite :: (hexagon.Suite) -> ())(t)
+					return nil
+				end)
+				if not registered then t.test("registers suite", function()
+					error(message, 0)
+				end) end
+			end)
+		end
+	end)
+	local cases_since_yield = 0
+	local last_yield = os.clock()
+	return HttpService:JSONEncode(hexagon.run(collection, {
+		mode = mode,
+		filter = options.filter,
+		onCaseComplete = function()
+			cases_since_yield += 1
+			if cases_since_yield < CASES_PER_YIELD and os.clock() - last_yield < MAX_SECONDS_WITHOUT_YIELD then return end
+			task_scheduler.wait()
+			cases_since_yield = 0
+			last_yield = os.clock()
+		end,
+	}))
+end
+
+function module.list(request: RunRequest?): string
+	local options: RunRequest = request or ({} :: RunRequest)
+	local mode: "test" | "bench" | "all" = options.mode or "all"
+	local suites: { string } = {}
+	for _, module_script in discover(mode) do
+		table.insert(suites, module_script:GetFullName())
+	end
+	return HttpService:JSONEncode {
+		schema_version = 1,
+		suites = suites,
+	}
+end
+
+return table.freeze(module)

package/runtime/encode_json.luau

@@ -0,0 +1,57 @@
+--!strict
+-- Native Luau JSON encoder for runner reports.
+
+-- Kept dependency-free so the native Luau runner and Roblox use the same data.
+
+local function escape(value: string): string
+	return '"'
+		.. value:gsub('[%z\1-\31\\"]', function(character)
+			local replacements: { [string]: string } = {
+				['"'] = '\\"',
+				["\\"] = "\\\\",
+				["\b"] = "\\b",
+				["\f"] = "\\f",
+				["\n"] = "\\n",
+				["\r"] = "\\r",
+				["\t"] = "\\t",
+			}
+			local code = string.byte(character) :: number
+			return replacements[character] or string.format("\\u%04x", code)
+		end)
+		.. '"'
+end
+
+local function encode(value: unknown): string
+	local kind = type(value)
+	if value == nil then return "null" end
+	if kind == "boolean" or kind == "number" then return tostring(value) end
+	if kind == "string" then return escape(value :: string) end
+	if kind ~= "table" then error(`cannot encode {kind} as JSON`, 2) end
+
+	local object = value :: { [unknown]: unknown }
+	local length = #object
+	local array = true
+	local count = 0
+	for key in object do
+		count += 1
+		if type(key) ~= "number" or key < 1 or key > length or key ~= math.floor(key) then array = false end
+	end
+	array = array and count == length
+
+	local parts = {}
+	if array then
+		for index = 1, length do
+			parts[index] = encode(object[index])
+		end
+		return "[" .. table.concat(parts, ",") .. "]"
+	end
+
+	for key, item in object do
+		if type(key) ~= "string" then error("JSON object keys must be strings", 2) end
+		table.insert(parts, `{escape(key)}:{encode(item)}`)
+	end
+	table.sort(parts)
+	return "{" .. table.concat(parts, ",") .. "}"
+end
+
+return encode

package/runtime/expect.luau

@@ -0,0 +1,125 @@
+--!strict
+-- Shared native Luau and Roblox expectations.
+
+local quote = require("./quote")
+
+export type Expectation = {
+	never: Expectation,
+	toBe: (expected: unknown) -> Expectation,
+	toEqual: (expected: unknown) -> Expectation,
+	toBeNear: (expected: number, tolerance: number?) -> Expectation,
+	toBeTruthy: () -> Expectation,
+	toExist: () -> Expectation,
+	toHaveType: (expected: string) -> Expectation,
+	toHaveKey: (expected: unknown) -> Expectation,
+	toContain: (expected: unknown) -> Expectation,
+	toMatch: (pattern: string) -> Expectation,
+	toThrow: (pattern: string?) -> Expectation,
+}
+
+local function deep_equal(left: unknown, right: unknown, seen: { [any]: any }): boolean
+	if left == right then return true end
+	if type(left) ~= "table" or type(right) ~= "table" then return false end
+	local left_table = left :: { [unknown]: unknown }
+	local right_table = right :: { [unknown]: unknown }
+	if seen[left_table] ~= nil then return seen[left_table] == right_table end
+	seen[left_table] = right_table
+	for key, value in left_table do
+		if not deep_equal(value, right_table[key], seen) then return false end
+	end
+	for key in right_table do
+		if left_table[key] == nil then return false end
+	end
+	return true
+end
+
+local function source_location(): (string, number, string)
+	for level = 3, 12 do
+		local source, line = debug.info(level, "sl")
+		if type(source) ~= "string" then break end
+		local implementation = source:find("/test/hexagon/expect", 1, true) or source:find("/test/hexagon/quote", 1, true)
+		if implementation == nil then return source, if type(line) == "number" then line else 0, debug.traceback(nil, level) end
+	end
+	local source, line = debug.info(3, "sl")
+	return if type(source) == "string" then source else "unknown", if type(line) == "number" then line else 0, debug.traceback(nil, 3)
+end
+
+local function fail(actual: unknown, assertion: string, expected: unknown, detail: string?): never
+	local source, line, trace = source_location()
+	local message = `expected {quote(actual)} {assertion}`
+	if expected ~= nil then
+		message ..= ` {quote(expected)}`
+	end
+	if detail ~= nil then
+		message ..= `\n{detail}`
+	end
+	error({
+		type = "hexagon.error",
+		source = source,
+		line = line,
+		message = message,
+		trace = trace,
+	}, 0)
+end
+
+local function expect(actual: unknown): Expectation
+	local function make(negated: boolean): Expectation
+		local self = {} :: any
+		local function check(ok: boolean, assertion: string, expected: unknown, detail: string?): Expectation
+			if ok == negated then fail(actual, if negated then `not {assertion}` else assertion, expected, detail) end
+			return self
+		end
+
+		self.toBe = function(expected: unknown)
+			return check(actual == expected, "to be", expected, nil)
+		end
+		self.toEqual = function(expected: unknown)
+			return check(deep_equal(actual, expected, {}), "to equal", expected, nil)
+		end
+		self.toBeNear = function(expected: number, tolerance: number?)
+			local epsilon = tolerance or 1e-6
+			if typeof(actual) ~= "number" then fail(actual, "to be a number near", expected, nil) end
+			if epsilon < 0 then error("expect().toBeNear() tolerance must be non-negative", 2) end
+			return check(math.abs((actual :: number) - expected) <= epsilon, "to be near", expected, `tolerance: {epsilon}`)
+		end
+		self.toBeTruthy = function()
+			return check(actual ~= nil and actual ~= false, "to be truthy", nil, nil)
+		end
+		self.toExist = function()
+			return check(actual ~= nil, "to exist", nil, nil)
+		end
+		self.toHaveType = function(expected: string)
+			return check(typeof(actual) == expected, "to have type", expected, `actual type: {typeof(actual)}`)
+		end
+		self.toHaveKey = function(expected: unknown)
+			if type(actual) ~= "table" then fail(actual, "to be a table containing key", expected, nil) end
+			return check((actual :: { [unknown]: unknown })[expected] ~= nil, "to have key", expected, nil)
+		end
+		self.toContain = function(expected: unknown)
+			if type(actual) ~= "table" then fail(actual, "to be an array containing", expected, nil) end
+			return check(table.find(actual :: { unknown }, expected) ~= nil, "to contain", expected, nil)
+		end
+		self.toMatch = function(pattern: string)
+			if type(actual) ~= "string" then fail(actual, "to be a string matching", pattern, nil) end
+			return check((actual :: string):match(pattern) ~= nil, "to match", pattern, nil)
+		end
+		self.toThrow = function(pattern: string?)
+			if type(actual) ~= "function" then fail(actual, "to be a function that throws", pattern, nil) end
+			local ok, message = pcall(function(): unknown
+				(actual :: () -> ())()
+				return nil
+			end)
+			local matches = not ok and (pattern == nil or tostring(message):match(pattern) ~= nil)
+			return check(matches, "to throw", pattern, if ok then "function returned successfully" else `threw: {message}`)
+		end
+		return self
+	end
+
+	local positive = make(false)
+	local negative = make(true)
+	positive.never = negative
+	negative.never = positive
+	return positive
+end
+
+return expect