@maligator/cli 0.1.0-alpha.23 → 0.1.0-alpha.24

package/index.d.ts

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

package/package.json

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

package/platform-api.d.ts

@@ -0,0 +1,3 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+import "./process-api.d.ts";
+import "./test-api.d.ts";

package/process-api.d.ts

@@ -0,0 +1,278 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Application execution context. Importing this module has no externally observable
+ * effects and requires no configuration switch. Unused exports and native
+ * implementation dependencies are eliminated. Process arguments, environment, working
+ * directory, and PID are runtime concerns outside execution.
+ */
+declare module "maligator:process" {
+	/**
+	 * Profiling instrumentation: none by default; sampling for --profile; compiler for
+	 * --profile=compiler. Both profiling modes select full optimization without
+	 * selecting production application behavior.
+	 */
+	export type ExecutionProfile = "none" | "sampling" | "compiler";
+
+	/**
+	 * The fixed platform contract of the application image.
+	 */
+	export type ExecutionTarget = {
+		/**
+		 * Application operating-system target, not the compiler host. Native builds use
+		 * darwin or linux; WebAssembly uses wasi.
+		 */
+		readonly platform: "darwin" | "linux" | "wasi";
+		/**
+		 * Application architecture. Cross builds report the destination architecture.
+		 */
+		readonly arch: "arm64" | "x64" | "wasm32";
+		/**
+		 * Resolved target triple, including when --target was omitted; for example
+		 * aarch64-apple-darwin.
+		 */
+		readonly triple: string;
+	};
+
+	/**
+	 * Options shared by build, run, and dev. Output paths, verbosity, and compiler
+	 * scheduling are tool settings and are not exposed.
+	 */
+	export type ExecutionOptions = {
+		/**
+		 * Selected application profiling instrumentation. Defaults to none; does not imply
+		 * execution.production.
+		 */
+		readonly profile: ExecutionProfile;
+	};
+
+	/**
+	 * Normalized test settings, fixed for the application image. Changing these values
+	 * invalidates specialized test artifacts.
+	 */
+	export type TestExecutionOptions = {
+		/**
+		 * Selected test profiling instrumentation. Defaults to none; profiling preserves
+		 * command: test.
+		 */
+		readonly profile: ExecutionProfile;
+		/**
+		 * Hierarchical test-name filter from --run, or null when all discovered names are
+		 * eligible.
+		 */
+		readonly nameFilter: string | null;
+		/**
+		 * Number of requested test repetitions from --repeat; defaults to 1. This is not
+		 * the currently executing repetition.
+		 */
+		readonly repeat: number;
+		/**
+		 * Whether --bail stops the test run after its first failure. Defaults to false.
+		 */
+		readonly bail: boolean;
+		/**
+		 * Default test timeout in milliseconds from --timeout. Defaults to 5000; individual
+		 * test APIs can select a different timeout.
+		 */
+		readonly timeoutMs: number;
+		/**
+		 * Resolved positive shuffle seed, or null when shuffling is disabled. --shuffle
+		 * without a seed chooses it once before compilation; the same seed drives execution
+		 * and cache identity.
+		 */
+		readonly shuffleSeed: number | null;
+	};
+
+	/**
+	 * Resolved engine policies. These describe build inputs, never post-DCE native
+	 * feature inclusion.
+	 */
+	export type ExecutionEngineConfig = {
+		/**
+		 * Requested primordial mutation policy. Defaults to locked. The execution snapshot
+		 * itself is immutable in either policy.
+		 */
+		readonly primordials: "locked" | "mutable";
+		/**
+		 * Dynamic compilation policy. false (default) rejects eval/Function execution at
+		 * runtime; true enables the runtime compiler; compile-check additionally rejects
+		 * statically visible dynamic compilation calls.
+		 */
+		readonly eval: boolean | "compile-check";
+		/**
+		 * Whether additional realms are enabled. Defaults to false.
+		 */
+		readonly realms: boolean;
+		/**
+		 * Whether regular expressions are enabled. Defaults to true.
+		 */
+		readonly regexp: boolean;
+		/**
+		 * Whether Temporal and its required data are enabled. Defaults to false.
+		 */
+		readonly temporal: boolean;
+		/**
+		 * Requested Intl policy after applying configuration defaults.
+		 */
+		readonly intl: {
+			/**
+			 * Whether Intl is enabled. Defaults to false.
+			 */
+			readonly enabled: boolean;
+			/**
+			 * Requested Intl service names. An empty array selects the default complete
+			 * service set when Intl is enabled; it does not mean every service survived tree
+			 * shaking.
+			 */
+			readonly features: ReadonlyArray<string>;
+			/**
+			 * Requested locale selection. Defaults to an empty array. Unsupported locale
+			 * selections are rejected by configuration validation.
+			 */
+			readonly languages: ReadonlyArray<string>;
+		};
+	};
+
+	/**
+	 * Public application policies from the selected build configuration. Excludes
+	 * build-host paths, asset declarations, output controls, and the obsolete Maligator
+	 * surface switch.
+	 */
+	export type ExecutionConfig = {
+		/**
+		 * Engine configuration after validation and default resolution.
+		 */
+		readonly engine: ExecutionEngineConfig;
+		/**
+		 * Global and compatibility surface policy. maligator:process requires no enable
+		 * flag.
+		 */
+		readonly surface: {
+			/**
+			 * Whether Web globals are requested. Defaults to false; native module imports are
+			 * independent of this global installation policy.
+			 */
+			readonly webPlatform: boolean;
+			/**
+			 * Whether Node compatibility, globals, and node: module resolution are requested.
+			 * Defaults to false.
+			 */
+			readonly node: boolean;
+		};
+		/**
+		 * Resolved module-resolution policy.
+		 */
+		readonly modules: {
+			/**
+			 * Exact module-specifier replacements from configuration. Defaults to an empty
+			 * object. Alias entries are immutable own data properties.
+			 */
+			readonly aliases: Readonly<Record<string, string>>;
+		};
+	};
+
+	/**
+	 * Fields shared by every execution workflow. All nested objects and arrays are
+	 * deeply frozen at runtime.
+	 */
+	export type ExecutionCommon = {
+		/**
+		 * Explicit production application intent. True only when production was selected
+		 * for the application; independent of NODE_ENV, profiling, and optimization.
+		 * Currently --production is a build option. Defaults to false.
+		 */
+		readonly production: boolean;
+		/**
+		 * Whether the application image executes as native compiled code. A native
+		 * executable hosting an interpreted image reports false. This is fixed for the
+		 * image, not a query about the current stack frame or an eval-created function.
+		 */
+		readonly compiled: boolean;
+		/**
+		 * Actual selected frontend optimization policy. Ordinary commands currently use
+		 * development; production builds and profiling use full. Backend choice is
+		 * independent.
+		 */
+		readonly optimization: "development" | "full";
+		/**
+		 * Resolved application target. The compiler's host platform is not substituted
+		 * during a cross build.
+		 */
+		readonly target: ExecutionTarget;
+		/**
+		 * Validated configuration policies with defaults applied, captured before
+		 * compilation.
+		 */
+		readonly config: ExecutionConfig;
+	};
+
+	/**
+	 * An immutable application-image description, discriminated by command. The command
+	 * describes the workflow that prepared the image, not a transient process phase.
+	 */
+	export type Execution = ExecutionCommon &
+		(
+			| {
+					/**
+					 * Prepared by maligator build. Remains build when the resulting executable runs
+					 * later; application statements are not executed by the build itself.
+					 */
+					readonly command: "build";
+					/**
+					 * Normalized build options relevant to application execution.
+					 */
+					readonly options: ExecutionOptions;
+			  }
+			| {
+					/**
+					 * Prepared by maligator run or maligator dev. dev denotes the watch/restart
+					 * workflow even when profiling selects native compilation.
+					 */
+					readonly command: "run" | "dev";
+					/**
+					 * Normalized run/dev options. Arguments after -- remain runtime argv and do not
+					 * specialize application compilation.
+					 */
+					readonly options: ExecutionOptions;
+			  }
+			| {
+					/**
+					 * Prepared by maligator test. Preserved for interpreted tests, profiled native
+					 * tests, and every fragment of the test application.
+					 */
+					readonly command: "test";
+					/**
+					 * Normalized test options. Narrow command to test before accessing test-only
+					 * fields.
+					 */
+					readonly options: TestExecutionOptions;
+			  }
+		);
+
+	/**
+	 * The canonical execution description, fixed before application compilation. Reads
+	 * of known own properties, import aliases and re-exports, immutable aliases and
+	 * destructuring, primitive comparisons, boolean expressions, and if/switch branches
+	 * specialize in development and full compilation. Dynamic keys and opaque calls
+	 * remain ordinary JavaScript and may retain the runtime object. The snapshot has
+	 * stable identity within an application context and deeply frozen own data
+	 * properties; reflection sees the complete shape. Static and dynamic imports return
+	 * the same export. A different command, option, configuration, target, or backend
+	 * creates a different compilation context. Profiling does not change production
+	 * intent. Importing the module does not keep unused native code alive.
+	 *
+	 * @example
+	 * import { execution } from "maligator:process";
+	 *
+	 * if (execution.compiled && execution.production) {
+	 *   console.log("native production application");
+	 * }
+	 *
+	 * @example
+	 * import { execution } from "maligator:process";
+	 *
+	 * if (execution.command === "test") {
+	 *   console.log(execution.options.repeat);
+	 * }
+	 */
+	export const execution: Execution;
+}

package/test-api.d.ts

@@ -1,25 +1,40 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Test authoring and assertions. Importing this module does not register tests or
+ * install runner globals. Registration and assertions are ordinary effectful calls;
+ * the test command initializes its internal runner explicitly. Unused imports can be
+ * eliminated.
+ */
 declare module "maligator:test" {
 	/**
-	 * A test or hook body. Maligator waits for a returned promise or thenable
-	 * before advancing the lifecycle.
+	 * 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. */
+
+	/**
+	 * 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}. */
+
+	/**
+	 * 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.
+	 * 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 {
+	export type AsymmetricMatcher = {
 		readonly __maligator_asymmetric__: string;
-	}
+	};
 
-	/** Matchers for a synchronously received value. */
-	export interface Matchers {
+	/**
+	 * Matchers for a synchronously received value.
+	 */
+	export type Matchers = {
 		/** Negate the following matcher. */
 		readonly not: Matchers;
 		/** Wait for the received promise to fulfill, then match its value. */
@@ -65,14 +80,14 @@ declare module "maligator:test" {
 				| 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.
+	 * 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 {
+	export type AsyncMatchers = {
 		/** Negate the following asynchronous matcher. */
 		readonly not: AsyncMatchers;
 		toBe(expected: unknown): Promise<void>;
@@ -94,10 +109,12 @@ declare module "maligator:test" {
 				| Error
 				| (abstract new (...args: Array<never>) => Error),
 		): Promise<void>;
-	}
+	};
 
-	/** Assertion entrypoint and Maligator-owned asymmetric matcher factories. */
-	export interface ExpectFunction {
+	/**
+	 * Assertion entrypoint and Maligator-owned asymmetric matcher factories.
+	 */
+	export type 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. */
@@ -110,10 +127,12 @@ declare module "maligator:test" {
 		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 tests in the current suite during module evaluation.
+	 */
+	export type TestFunction = {
 		/** Register a test. Returned promises are awaited by the runner. */
 		(name: string, callback: TestCallback): void;
 		/** Register a skipped test without invoking its callback. */
@@ -132,36 +151,48 @@ declare module "maligator:test" {
 		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 nested suites synchronously during module evaluation.
+	 */
+	export type 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. */
+	/**
+	 * Register a test in the current suite.
+	 */
 	export const test: TestFunction;
-	/** Register a nested suite in the current suite. */
+	/**
+	 * Register a nested suite in the current suite.
+	 */
 	export const describe: DescribeFunction;
-	/** Create fluent matchers for a received value. */
+	/**
+	 * 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 once before tests in the current suite.
+	 */
+	export const beforeAll: (callback: HookCallback) => void;
+	/**
+	 * Run once after tests in the current suite, including after test failures.
+	 */
+	export const 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;
+	export const beforeEach: (callback: HookCallback) => void;
 	/**
-	 * Run after every selected descendant test. Nested-suite hooks run before
-	 * ancestor hooks.
+	 * Run after every selected descendant test. Nested-suite hooks run before ancestor
+	 * hooks.
 	 */
-	export function afterEach(callback: HookCallback): void;
+	export const afterEach: (callback: HookCallback) => void;
 }