@maligator/cli 0.1.0-alpha.4 → 0.1.0-alpha.5

package/README.md

@@ -50,11 +50,116 @@ maligator init
 maligator doctor [--verbose] [--target rust-triple]
 maligator build [entry] [--production] [--artifact directory] [--target rust-triple] [--config path]
 maligator run [entry] [--config path] [-- args...]
+maligator test [path ...] [--run name] [--shuffle [seed]] [--repeat count] [--bail]
 ```
 
 Run commands from the project root. Maligator does not search parent directories
 for configuration.
 
+## Testing
+
+`maligator test` discovers conventional JavaScript and erasable-TypeScript test
+files and runs them through Maligator's embedded interpreter. Test runs do not
+generate C or invoke the native toolchain. Import the Maligator-owned API from
+`maligator:test`:
+
+```typescript
+import { beforeEach, describe, expect, test } from "maligator:test";
+import { createRouter, RouteError, type Router } from "./router.ts";
+
+describe("router", () => {
+	let router: Router;
+
+	beforeEach(() => {
+		router = createRouter();
+	});
+
+	test("matches parameters", async () => {
+		await expect(router.match("/users/42")).resolves.toMatchObject({
+			id: expect.any(Number),
+		});
+	});
+
+	test("rejects malformed parameters", async () => {
+		await expect(router.match("/users/nope")).rejects.toThrow(RouteError);
+	});
+});
+```
+
+By default, discovery includes `*.test.js`, `*.test.mjs`, `*.test.ts`,
+`*.test.mts`, and the corresponding `*.spec.*` names. Pass files, directories,
+or both:
+
+```shell
+maligator test
+maligator test src/router
+maligator test src/router/router.test.ts
+maligator test --run "router > parameters"
+maligator test --shuffle
+maligator test --shuffle 18492
+maligator test --repeat 10
+maligator test --bail
+```
+
+`--run` filters hierarchical suite and test names. `--shuffle [seed]` changes
+execution order reproducibly and always prints the seed. `--repeat` executes the
+selected tests again while reusing unchanged compilation artifacts. The default
+policy completes the selected suite; `--bail` stops scheduling after the first
+failure.
+
+The authoring API includes nested `describe` suites, `beforeAll`, `afterAll`,
+`beforeEach`, `afterEach`, synchronous and promise-returning callbacks,
+`test.skip`, `test.todo`, `test.only`, and `test.each`. A committed `.only`
+focuses execution and prints a warning. Matchers include identity, structural
+equality, truthiness, containment, length, string/regular-expression matching,
+partial-object matching, throwing, `.not`, `.resolves`, `.rejects`, and the
+`expect.any`, `expect.anything`, `expect.stringMatching`,
+`expect.objectContaining`, and `expect.arrayContaining` asymmetric helpers.
+Maligator owns this API and does not claim Jest, Vitest, or `node:test`
+compatibility.
+
+Test files currently execute serially in one Realm. Registration and lifecycle
+state are separated by test file, but globals, prototypes, imported module
+singletons, host state, and asynchronous work left running by a test can be
+shared. Do not rely on process-per-file isolation.
+
+Frontend bytecode is content-addressed by source, transitive dependencies,
+resolved module identities, relevant build configuration, and compiler/runtime
+format versions. A warm run restores a shared base plus independently cached
+test-file registration fragments. Test results are never cached: every selected
+test executes on every invocation.
+
+The package ships documented declarations for `maligator:test`. Projects whose
+TypeScript configuration does not include `maligator.build.ts` should load the
+package declarations explicitly:
+
+```json
+{
+	"compilerOptions": {
+		"types": ["@maligator/cli"]
+	}
+}
+```
+
+## Build cache
+
+Normal `maligator build` and `maligator run` commands use the same portable VM
+definition format for their frontend cache. On a valid hit, Maligator skips
+parsing, module-graph construction, semantic analysis, optimization, register
+allocation, and VM lowering, then emits the same native translation units from
+the restored definition. Generated translation units and the native driver are
+compiled into independently content-addressed objects, so unchanged objects can
+be relinked without repeating C compilation. The final link still runs, and
+native runtime and Rust archives remain separately content-addressed.
+
+Build cache invalidation includes source and transitive dependency content,
+package-resolution metadata, relevant configuration, the TypeScript erasure
+frontend, and compiler/wire versions. Generated-object identity additionally
+includes the exact C source, source identity, native headers/runtime artifact,
+compiler/toolchain, target, flags, and build environment. Compiler diagnostic
+dump flags deliberately recompile the frontend because they require live
+semantic and IR objects.
+
 ## Production builds
 
 Use production mode for a deployable binary:

package/index.d.ts

@@ -1,5 +1,7 @@
 /// <reference lib="dom" />
 
+import "./test-api.d.ts";
+
 export type MaligatorIntlFeature =
 	| "collator"
 	| "number-format"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@maligator/cli",
-	"version": "0.1.0-alpha.4",
+	"version": "0.1.0-alpha.5",
 	"description": "Ahead-of-time JavaScript compiler and native runtime",
 	"license": "MIT",
 	"homepage": "https://github.com/dirkdev98/maligator#readme",
@@ -30,6 +30,7 @@
 		"bin/maligator.js",
 		"index.js",
 		"index.d.ts",
+		"test-api.d.ts",
 		"README.md",
 		"LICENSE"
 	],
@@ -44,6 +45,6 @@
 		}
 	},
 	"optionalDependencies": {
-		"@maligator/cli-darwin-arm64": "0.1.0-alpha.4"
+		"@maligator/cli-darwin-arm64": "0.1.0-alpha.5"
 	}
 }

package/test-api.d.ts

@@ -0,0 +1,167 @@
+declare module "maligator:test" {
+	/**
+	 * A test or hook body. Maligator waits for a returned promise or thenable
+	 * before advancing the lifecycle.
+	 */
+	export type TestCallback = () => unknown;
+	/** A lifecycle hook body, with the same async completion contract as a test. */
+	export type HookCallback = TestCallback;
+	/** A constructable value accepted by {@link expect.any}. */
+	export type Constructor = abstract new (...args: Array<never>) => unknown;
+
+	/**
+	 * Opaque partial-match value produced by helpers such as
+	 * {@link expect.objectContaining}. It may be nested inside `toEqual`,
+	 * `toStrictEqual`, and `toMatchObject` expectations.
+	 */
+	export interface AsymmetricMatcher {
+		readonly __maligator_asymmetric__: string;
+	}
+
+	/** Matchers for a synchronously received value. */
+	export interface Matchers {
+		/** Negate the following matcher. */
+		readonly not: Matchers;
+		/** Wait for the received promise to fulfill, then match its value. */
+		readonly resolves: AsyncMatchers;
+		/** Wait for the received promise to reject, then match its reason. */
+		readonly rejects: AsyncMatchers;
+		/** Require ECMAScript `Object.is` identity. */
+		toBe(expected: unknown): void;
+		/** Recursively compare enumerable object properties and array elements. */
+		toEqual(expected: unknown): void;
+		/**
+		 * Recursively compare values while also requiring matching prototypes and
+		 * matching sparse-array holes.
+		 */
+		toStrictEqual(expected: unknown): void;
+		/** Require a value other than `undefined`. */
+		toBeDefined(): void;
+		/** Require `undefined`. */
+		toBeUndefined(): void;
+		/** Require `null`. */
+		toBeNull(): void;
+		/** Require a truthy value. */
+		toBeTruthy(): void;
+		/** Require a falsy value. */
+		toBeFalsy(): void;
+		/** Require a string substring or an array element matched by identity. */
+		toContain(expected: unknown): void;
+		/** Require a numeric `.length` equal to `expected`. */
+		toHaveLength(expected: number): void;
+		/** Match a string against a substring or regular expression. */
+		toMatch(expected: string | RegExp): void;
+		/** Recursively require the enumerable properties present in `expected`. */
+		toMatchObject(expected: object): void;
+		/**
+		 * Invoke the received function and require it to throw. The optional
+		 * expectation may be a message substring, regular expression, error
+		 * constructor, or error instance.
+		 */
+		toThrow(
+			expected?:
+				| string
+				| RegExp
+				| Error
+				| (abstract new (...args: Array<never>) => Error),
+		): void;
+	}
+
+	/**
+	 * Promise-returning matcher surface exposed by {@link Matchers.resolves} and
+	 * {@link Matchers.rejects}. Await these calls so the test cannot finish before
+	 * the assertion.
+	 */
+	export interface AsyncMatchers {
+		/** Negate the following asynchronous matcher. */
+		readonly not: AsyncMatchers;
+		toBe(expected: unknown): Promise<void>;
+		toEqual(expected: unknown): Promise<void>;
+		toStrictEqual(expected: unknown): Promise<void>;
+		toBeDefined(): Promise<void>;
+		toBeUndefined(): Promise<void>;
+		toBeNull(): Promise<void>;
+		toBeTruthy(): Promise<void>;
+		toBeFalsy(): Promise<void>;
+		toContain(expected: unknown): Promise<void>;
+		toHaveLength(expected: number): Promise<void>;
+		toMatch(expected: string | RegExp): Promise<void>;
+		toMatchObject(expected: object): Promise<void>;
+		toThrow(
+			expected?:
+				| string
+				| RegExp
+				| Error
+				| (abstract new (...args: Array<never>) => Error),
+		): Promise<void>;
+	}
+
+	/** Assertion entrypoint and Maligator-owned asymmetric matcher factories. */
+	export interface ExpectFunction {
+		/** Create matchers for `received`. The assertion position is captured here. */
+		(received: unknown): Matchers;
+		/** Match a primitive of the corresponding built-in kind or an instance. */
+		any(constructorValue: Constructor): AsymmetricMatcher;
+		/** Match any value except `null` and `undefined`. */
+		anything(): AsymmetricMatcher;
+		/** Match a string containing `pattern` or satisfying the regular expression. */
+		stringMatching(pattern: string | RegExp): AsymmetricMatcher;
+		/** Match an object containing all recursively matched properties in `value`. */
+		objectContaining(value: object): AsymmetricMatcher;
+		/** Match an array containing a match for every element in `value`. */
+		arrayContaining(value: Array<unknown>): AsymmetricMatcher;
+	}
+
+	/** Register tests in the current suite during module evaluation. */
+	export interface TestFunction {
+		/** Register a test. Returned promises are awaited by the runner. */
+		(name: string, callback: TestCallback): void;
+		/** Register a skipped test without invoking its callback. */
+		skip(name: string, callback: TestCallback): void;
+		/** Register a named placeholder with no callback. */
+		todo(name: string): void;
+		/**
+		 * Register a focused test. When any `.only` exists, non-focused tests are
+		 * skipped and the runner emits a warning.
+		 */
+		only(name: string, callback: TestCallback): void;
+		/**
+		 * Register one test for each row. Use `%#` in `name` for the zero-based row
+		 * index. Array rows are spread into callback parameters.
+		 */
+		each<const Row extends ReadonlyArray<unknown>>(
+			rows: ReadonlyArray<Row>,
+		): (name: string, callback: (...values: [...Row]) => unknown) => void;
+	}
+
+	/** Register nested suites synchronously during module evaluation. */
+	export interface DescribeFunction {
+		/** Register a suite. Suite callbacks must not return a promise. */
+		(name: string, callback: () => void): void;
+		/** Register a suite whose descendants are skipped. */
+		skip(name: string, callback: () => void): void;
+		/** Register a focused suite and emit the runner's focused-test warning. */
+		only(name: string, callback: () => void): void;
+	}
+
+	/** Register a test in the current suite. */
+	export const test: TestFunction;
+	/** Register a nested suite in the current suite. */
+	export const describe: DescribeFunction;
+	/** Create fluent matchers for a received value. */
+	export const expect: ExpectFunction;
+	/** Run once before tests in the current suite. */
+	export function beforeAll(callback: HookCallback): void;
+	/** Run once after tests in the current suite, including after test failures. */
+	export function afterAll(callback: HookCallback): void;
+	/**
+	 * Run before every selected descendant test. Ancestor hooks run before hooks
+	 * declared by a nested suite.
+	 */
+	export function beforeEach(callback: HookCallback): void;
+	/**
+	 * Run after every selected descendant test. Nested-suite hooks run before
+	 * ancestor hooks.
+	 */
+	export function afterEach(callback: HookCallback): void;
+}