@hautajoki/hexagon 0.1.0

package/src/bundle.ts

@@ -0,0 +1,128 @@
+import { mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BUNDLE_VERSION = 1;
+const CLOUD_BUNDLE_FILES = ['cloud_runner.luau', 'expect.luau', 'hexagon.luau', 'quote.luau'] as const;
+const LOCAL_BUNDLE_FILES = ['encode_json.luau', 'expect.luau', 'hexagon.luau', 'local_runner.luau', 'quote.luau'] as const;
+const MARKER = '.hexagon-bundle.json';
+
+interface Marker {
+	readonly format: 1;
+	readonly package: string;
+	readonly version: string;
+	readonly files: readonly string[];
+}
+
+interface PackageIdentity {
+	readonly name: string;
+	readonly version: string;
+}
+
+export interface RuntimeBundle {
+	readonly directory: string;
+	readonly cloudRunner: string;
+	readonly localRunner: string;
+	readonly cleanup: () => Promise<void>;
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+		throw error;
+	}
+}
+
+async function packageIdentity(): Promise<PackageIdentity> {
+	const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+	const value = JSON.parse(await readFile(path, 'utf8')) as Partial<PackageIdentity>;
+	if (typeof value.name !== 'string' || typeof value.version !== 'string') {
+		throw new Error(`Hexagon package metadata is invalid at ${path}`);
+	}
+	return { name: value.name, version: value.version };
+}
+
+async function readMarker(directory: string, identity: PackageIdentity): Promise<Marker | undefined> {
+	const path = join(directory, MARKER);
+	if (!(await exists(path))) return undefined;
+	const value = JSON.parse(await readFile(path, 'utf8')) as Partial<Marker>;
+	if (
+		value.format !== BUNDLE_VERSION ||
+		value.package !== identity.name ||
+		value.version !== identity.version ||
+		!Array.isArray(value.files)
+	) {
+		throw new Error(`refusing to replace an incompatible Hexagon bundle at ${directory}`);
+	}
+	return value as Marker;
+}
+
+async function assertOwned(directory: string, marker: Marker): Promise<void> {
+	const owned = new Set<string>([MARKER, ...marker.files]);
+	const unexpected = (await readdir(directory)).filter((entry) => !owned.has(entry));
+	if (unexpected.length > 0) {
+		throw new Error(`refusing to alter unexpected files in ${directory}: ${unexpected.join(', ')}`);
+	}
+}
+
+export async function materializeRuntime(sourceRoot: string, target: 'cloud' | 'local'): Promise<RuntimeBundle> {
+	const directory = resolve(sourceRoot, 'test', 'hexagon');
+	const parent = dirname(directory);
+	const parentExisted = await exists(parent);
+	const identity = await packageIdentity();
+	const marker = await readMarker(directory, identity);
+	if ((await exists(directory)) && marker === undefined) {
+		const entries = await readdir(directory);
+		if (entries.length > 0) {
+			throw new Error(`refusing to overwrite authored source at ${directory}; move it or pass a different --root`);
+		}
+	}
+	if (marker !== undefined) {
+		await assertOwned(directory, marker);
+		for (const file of marker.files) {
+			await rm(join(directory, file), { force: true });
+		}
+	}
+
+	const runtime = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'runtime');
+	const files = target === 'cloud' ? CLOUD_BUNDLE_FILES : LOCAL_BUNDLE_FILES;
+	await mkdir(directory, { recursive: true });
+	for (const file of files) {
+		const contents = await readFile(join(runtime, file));
+		await writeFile(join(directory, file), contents);
+	}
+	const next: Marker = {
+		format: BUNDLE_VERSION,
+		package: identity.name,
+		version: identity.version,
+		files,
+	};
+	await writeFile(join(directory, MARKER), `${JSON.stringify(next, undefined, '\t')}\n`);
+
+	return {
+		directory,
+		cloudRunner: 'ReplicatedStorage.shared.test.hexagon.cloud_runner',
+		localRunner: join(directory, 'local_runner.luau'),
+		cleanup: async () => {
+			const current = await readMarker(directory, identity);
+			if (current === undefined) return;
+			await assertOwned(directory, current);
+			for (const file of current.files) {
+				await rm(join(directory, file), { force: true });
+			}
+			await rm(join(directory, MARKER), { force: true });
+			await rmdir(directory);
+			if (!parentExisted) {
+				try {
+					await rmdir(parent);
+				} catch (error) {
+					const code = (error as NodeJS.ErrnoException).code;
+					if (code !== 'ENOENT' && code !== 'ENOTEMPTY') throw error;
+				}
+			}
+		},
+	};
+}

package/src/cli.ts

@@ -0,0 +1,441 @@
+#!/usr/bin/env bun
+
+import { dirname, relative, resolve, sep } from 'node:path';
+
+import { materializeRuntime } from './bundle.ts';
+import { discoverLocalSuites, type Mode } from './discovery.ts';
+import { aggregateReports, parseRunReport, parseTesseraRun, type RunReport, returnedString, type TesseraRunResult } from './protocol.ts';
+import { printReport } from './reporter.ts';
+
+type Isolation = 'file' | 'run';
+type CloudTarget = { readonly kind: 'fresh' } | { readonly kind: 'published' } | { readonly kind: 'version'; readonly version: number };
+
+interface Arguments {
+	readonly mode: Mode;
+	readonly filter?: string;
+	readonly cloud: boolean;
+	readonly root: string;
+	readonly place: string;
+	readonly environment?: string;
+	readonly config?: string;
+	readonly timeout: string;
+	readonly target: CloudTarget;
+	readonly codegen: boolean;
+	readonly isolation: Isolation;
+	readonly allowFocused: boolean;
+	readonly json: boolean;
+	readonly color: boolean;
+	readonly runner?: string;
+}
+
+interface CommandResult {
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+interface HexagonResult {
+	readonly schema_version: 1;
+	readonly target: 'local' | 'cloud';
+	readonly isolation: Isolation;
+	readonly report: RunReport;
+	readonly executions: readonly TesseraRunResult[];
+}
+
+class HelpRequested extends Error {}
+
+function usage(): string {
+	return `Hexagon tests and benchmarks
+
+Usage:
+  hexagon <test|bench> [filter] [options]
+
+Options:
+  --cloud                 Run suites from an exact Roblox artifact
+  --filter <text>         Match a case path by case-insensitive substring
+  --root <directory>      Source root (default src)
+  --isolation <file|run>  Fresh VM/DataModel per suite file or one shared run
+  --place <name>          Tessera logical place (default main)
+  --environment <name>    Tessera environment
+  --config <path>         Tessera config path
+  --timeout <duration>    Tessera execution timeout (default 5m)
+  --version <number>      Run an existing exact place version
+  --published             Run mutable published head (cloud, run isolation only)
+  --runner <DataModel>    Override the bundled cloud runner path
+  --interpreted           Disable native code generation locally
+  --allow-focused         Permit global .only cases (requires run isolation)
+  --json                  Emit one machine-readable result
+  --no-color              Disable ANSI output
+  --help                  Show this help`;
+}
+
+function required(args: readonly string[], index: number, option: string): string {
+	const value = args[index];
+	if (value === undefined || value.startsWith('--')) {
+		throw new TypeError(`${option} requires a value`);
+	}
+	return value;
+}
+
+export function parseArguments(args: readonly string[], environment: NodeJS.ProcessEnv = process.env): Arguments {
+	const mode = args[0];
+	if (mode === undefined || mode === '--help' || mode === '-h') {
+		throw new HelpRequested();
+	}
+	if (mode !== 'test' && mode !== 'bench') {
+		throw new TypeError(`expected test or bench, got ${mode}`);
+	}
+
+	let filter: string | undefined;
+	let cloud = false;
+	let root = 'src';
+	let place = 'main';
+	let selectedEnvironment: string | undefined;
+	let config: string | undefined;
+	let timeout = '5m';
+	let target: CloudTarget = { kind: 'fresh' };
+	let targetSet = false;
+	let codegen = true;
+	let isolation: Isolation = 'file';
+	let allowFocused = false;
+	let json = false;
+	let color = environment.NO_COLOR === undefined;
+	let runner: string | undefined;
+
+	for (let index = 1; index < args.length; index += 1) {
+		const argument = args[index]!;
+		switch (argument) {
+			case '--help':
+			case '-h':
+				throw new HelpRequested();
+			case '--cloud':
+				cloud = true;
+				break;
+			case '--filter':
+				filter = required(args, ++index, '--filter');
+				break;
+			case '--root':
+				root = required(args, ++index, '--root');
+				break;
+			case '--place':
+				place = required(args, ++index, '--place');
+				break;
+			case '--environment':
+				selectedEnvironment = required(args, ++index, '--environment');
+				break;
+			case '--config':
+				config = required(args, ++index, '--config');
+				break;
+			case '--timeout':
+				timeout = required(args, ++index, '--timeout');
+				break;
+			case '--version': {
+				if (targetSet) throw new TypeError('select only one cloud artifact mode');
+				const raw = required(args, ++index, '--version');
+				const version = Number(raw);
+				if (!Number.isSafeInteger(version) || version <= 0) {
+					throw new TypeError('--version requires a positive integer');
+				}
+				target = { kind: 'version', version };
+				targetSet = true;
+				break;
+			}
+			case '--published':
+				if (targetSet) throw new TypeError('select only one cloud artifact mode');
+				target = { kind: 'published' };
+				targetSet = true;
+				break;
+			case '--runner':
+				runner = required(args, ++index, '--runner');
+				break;
+			case '--interpreted':
+				codegen = false;
+				break;
+			case '--isolation': {
+				const value = required(args, ++index, '--isolation');
+				if (value !== 'file' && value !== 'run') {
+					throw new TypeError('--isolation must be file or run');
+				}
+				isolation = value;
+				break;
+			}
+			case '--allow-focused':
+				allowFocused = true;
+				break;
+			case '--json':
+				json = true;
+				color = false;
+				break;
+			case '--no-color':
+				color = false;
+				break;
+			default:
+				if (argument.startsWith('--')) {
+					throw new TypeError(`unknown option: ${argument}`);
+				}
+				if (filter !== undefined) throw new TypeError(`unknown argument: ${argument}`);
+				filter = argument;
+		}
+	}
+
+	if (!cloud && targetSet) throw new TypeError('cloud artifact options require --cloud');
+	if (cloud && !codegen) throw new TypeError('--interpreted only applies to local runs');
+	if (!cloud && (selectedEnvironment !== undefined || config !== undefined || runner !== undefined)) {
+		throw new TypeError('Tessera options require --cloud');
+	}
+	if (cloud && target.kind === 'published' && isolation === 'file') {
+		throw new TypeError('--published cannot guarantee one version across isolated files; use --isolation run');
+	}
+	if (allowFocused && isolation === 'file') {
+		throw new TypeError('--allow-focused requires --isolation run so focus applies globally');
+	}
+
+	return {
+		mode,
+		...(filter === undefined ? {} : { filter }),
+		cloud,
+		root,
+		place,
+		...(selectedEnvironment === undefined ? {} : { environment: selectedEnvironment }),
+		...(config === undefined ? {} : { config }),
+		timeout,
+		target,
+		codegen,
+		isolation,
+		allowFocused,
+		json,
+		color,
+		...(runner === undefined ? {} : { runner }),
+	};
+}
+
+async function consume(stream: ReadableStream<Uint8Array>, forward: boolean): Promise<string> {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let output = '';
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		const text = decoder.decode(value, { stream: true });
+		output += text;
+		if (forward) process.stderr.write(text);
+	}
+	output += decoder.decode();
+	return output;
+}
+
+async function execute(command: readonly string[], cwd: string, streamStderr: boolean): Promise<CommandResult> {
+	const child = Bun.spawn([...command], {
+		cwd,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(child.stdout).text(),
+		consume(child.stderr as ReadableStream<Uint8Array>, streamStderr),
+		child.exited,
+	]);
+	if (exitCode !== 0) {
+		if (!streamStderr && stderr !== '') process.stderr.write(stderr);
+		throw new Error(`${command[0]} exited with code ${exitCode}`);
+	}
+	return { stdout, stderr };
+}
+
+function moduleArgument(runner: string, suite: string): string {
+	let path = relative(dirname(runner), suite).split(sep).join('/');
+	if (!path.startsWith('.')) path = `./${path}`;
+	return path.replace(/\.luau$/, '');
+}
+
+async function runLocalGroup(arguments_: Arguments, projectRoot: string, runner: string, suites: readonly string[]): Promise<RunReport> {
+	const command = ['luau'];
+	if (arguments_.codegen) command.push('--codegen');
+	command.push('-O2', runner, '-a', arguments_.mode, arguments_.filter ?? '-');
+	const sourceRoot = resolve(projectRoot, arguments_.root);
+	for (const suite of suites) {
+		command.push(
+			moduleArgument(runner, suite),
+			relative(sourceRoot, suite)
+				.split(sep)
+				.join('/')
+				.replace(/\.luau$/, ''),
+		);
+	}
+	const result = await execute(command, projectRoot, false);
+	const match = result.stdout.match(/(?:^|\n)HEXAGON_JSON:(.+)\r?\n?$/s);
+	if (match === null) {
+		if (result.stdout !== '') process.stderr.write(result.stdout);
+		throw new Error('native runner did not return a Hexagon report');
+	}
+	const diagnostics = result.stdout.slice(0, match.index).trim();
+	if (diagnostics !== '') process.stderr.write(`${diagnostics}\n`);
+	return parseRunReport(match[1]!);
+}
+
+async function runLocal(arguments_: Arguments, projectRoot: string): Promise<HexagonResult> {
+	const sourceRoot = resolve(projectRoot, arguments_.root);
+	const bundle = await materializeRuntime(sourceRoot, 'local');
+	const reports: RunReport[] = [];
+	try {
+		const suites = await discoverLocalSuites(sourceRoot, arguments_.mode);
+		if (arguments_.isolation === 'run') {
+			if (suites.length > 0) {
+				reports.push(await runLocalGroup(arguments_, projectRoot, bundle.localRunner, suites));
+			}
+		} else {
+			for (const suite of suites) {
+				reports.push(await runLocalGroup(arguments_, projectRoot, bundle.localRunner, [suite]));
+			}
+		}
+	} finally {
+		await bundle.cleanup();
+	}
+	return {
+		schema_version: 1,
+		target: 'local',
+		isolation: arguments_.isolation,
+		report: aggregateReports(arguments_.mode, arguments_.filter, reports),
+		executions: [],
+	};
+}
+
+function tesseraCommand(
+	arguments_: Arguments,
+	runner: string,
+	method: 'list' | 'run',
+	request: Record<string, unknown>,
+	target: CloudTarget,
+): string[] {
+	const command = [
+		'tessera',
+		'run',
+		'--json',
+		'--logs',
+		'--module',
+		runner,
+		'--method',
+		method,
+		'--args',
+		JSON.stringify([request]),
+		'--timeout',
+		arguments_.timeout,
+	];
+	if (arguments_.environment !== undefined) {
+		command.push('--environment', arguments_.environment);
+	}
+	if (arguments_.config !== undefined) command.push('--config', arguments_.config);
+	if (target.kind === 'fresh') command.push('--fresh');
+	else if (target.kind === 'version') command.push('--version', String(target.version));
+	command.push(arguments_.place);
+	return command;
+}
+
+async function runTessera(
+	arguments_: Arguments,
+	projectRoot: string,
+	runner: string,
+	method: 'list' | 'run',
+	request: Record<string, unknown>,
+	target: CloudTarget,
+): Promise<TesseraRunResult> {
+	const result = await execute(tesseraCommand(arguments_, runner, method, request, target), projectRoot, !arguments_.json);
+	return parseTesseraRun(result.stdout);
+}
+
+function printExecutionLogs(result: TesseraRunResult, json: boolean): void {
+	if (json) return;
+	for (const line of result.logs ?? []) process.stderr.write(`${line}\n`);
+}
+
+async function runCloud(arguments_: Arguments, projectRoot: string): Promise<HexagonResult> {
+	const bundle = await materializeRuntime(resolve(projectRoot, arguments_.root), 'cloud');
+	const runner = arguments_.runner ?? bundle.cloudRunner;
+	const reports: RunReport[] = [];
+	const executions: TesseraRunResult[] = [];
+	try {
+		const baseRequest: Record<string, unknown> = { mode: arguments_.mode };
+		if (arguments_.filter !== undefined) baseRequest.filter = arguments_.filter;
+		if (arguments_.isolation === 'run') {
+			const execution = await runTessera(arguments_, projectRoot, runner, 'run', baseRequest, arguments_.target);
+			executions.push(execution);
+			printExecutionLogs(execution, arguments_.json);
+			reports.push(parseRunReport(returnedString(execution, 'cloud runner')));
+		} else {
+			const discovery = await runTessera(arguments_, projectRoot, runner, 'list', { mode: arguments_.mode }, arguments_.target);
+			executions.push(discovery);
+			printExecutionLogs(discovery, arguments_.json);
+			const manifest = JSON.parse(returnedString(discovery, 'cloud discovery')) as { schema_version?: unknown; suites?: unknown };
+			if (manifest.schema_version !== 1 || !Array.isArray(manifest.suites)) {
+				throw new Error('cloud discovery returned an unsupported suite manifest');
+			}
+			const suites = manifest.suites.map((suite) => {
+				if (typeof suite !== 'string') {
+					throw new TypeError('cloud suite manifest contains a non-string path');
+				}
+				return suite;
+			});
+			const version = discovery.version;
+			if (version === undefined || version <= 0) {
+				throw new Error('isolated cloud runs require an exact saved place version');
+			}
+			for (const suite of suites) {
+				const execution = await runTessera(arguments_, projectRoot, runner, 'run', { ...baseRequest, suite }, { kind: 'version', version });
+				executions.push(execution);
+				printExecutionLogs(execution, arguments_.json);
+				reports.push(parseRunReport(returnedString(execution, `suite ${suite}`)));
+			}
+		}
+	} finally {
+		await bundle.cleanup();
+	}
+	return {
+		schema_version: 1,
+		target: 'cloud',
+		isolation: arguments_.isolation,
+		report: aggregateReports(arguments_.mode, arguments_.filter, reports),
+		executions,
+	};
+}
+
+export function policyFailure(result: HexagonResult, arguments_: Arguments): string | undefined {
+	if (result.report.selected === 0) return 'no cases were selected';
+	if (result.report.focused && !arguments_.allowFocused) {
+		return 'focused cases are not allowed; remove `.only` or pass --allow-focused for an intentional run';
+	}
+	if (!result.report.ok) return 'one or more cases failed';
+	return undefined;
+}
+
+export async function runCLI(rawArguments: readonly string[], cwd = process.cwd()): Promise<number> {
+	let arguments_: Arguments;
+	try {
+		arguments_ = parseArguments(rawArguments);
+	} catch (error) {
+		if (error instanceof HelpRequested) {
+			process.stdout.write(`${usage()}\n`);
+			return 0;
+		}
+		throw error;
+	}
+
+	const result = arguments_.cloud ? await runCloud(arguments_, cwd) : await runLocal(arguments_, cwd);
+	if (arguments_.json) process.stdout.write(`${JSON.stringify(result)}\n`);
+	else printReport(result.report, { color: arguments_.color });
+
+	const failure = policyFailure(result, arguments_);
+	if (failure !== undefined) {
+		if (!arguments_.json) process.stderr.write(`hexagon: ${failure}\n`);
+		return 1;
+	}
+	return 0;
+}
+
+if (import.meta.main) {
+	try {
+		process.exitCode = await runCLI(Bun.argv.slice(2));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`hexagon: ${message}\n`);
+		process.exitCode = 1;
+	}
+}

package/src/discovery.ts

@@ -0,0 +1,32 @@
+import { readdir } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+
+export type Mode = 'test' | 'bench';
+
+function suffix(mode: Mode): string {
+	return mode === 'test' ? '.local.spec.luau' : '.local.bench.luau';
+}
+
+export async function discoverLocalSuites(root: string, mode: Mode): Promise<string[]> {
+	const sourceRoot = resolve(root);
+	const expected = suffix(mode);
+	const suites: string[] = [];
+
+	async function walk(directory: string): Promise<void> {
+		const entries = await readdir(directory, { withFileTypes: true });
+		entries.sort((left, right) => left.name.localeCompare(right.name));
+		for (const entry of entries) {
+			const path = resolve(directory, entry.name);
+			if (entry.isDirectory()) await walk(path);
+			else if (entry.isFile() && entry.name.endsWith(expected)) suites.push(path);
+		}
+	}
+
+	await walk(sourceRoot);
+	suites.sort((left, right) => relative(sourceRoot, left).localeCompare(relative(sourceRoot, right)));
+	return suites;
+}
+
+export function matchesCloudSuite(name: string, mode: Mode): boolean {
+	return mode === 'test' ? name.endsWith('.spec') : name.endsWith('.bench');
+}