@c9up/helix 0.1.8 → 0.1.9

package/dist/runtime/configure.js

@@ -0,0 +1,164 @@
+/**
+ * `configure({ plugins })` — the Japa/AdonisJS bootstrap entry.
+ *
+ * Following Japa precisely: the runtime core is plugin-agnostic, and every
+ * capability (HTTP `client`, `db`, fakes, …) ships as a PLUGIN that extends the
+ * injected test context. A plugin is a function handed a {@link PluginApi};
+ * it registers context properties via `api.context.macro` / `.getter` (the
+ * `TestContext.macro`/`getter` of Japa) and pairs that with a `declare module`
+ * augmentation for the types.
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from "@c9up/helix";
+ *   import { apiClient } from "@c9up/ream/testing";
+ *   await configure({ plugins: [apiClient({ baseUrl })] });
+ *
+ * This keeps `@c9up/helix` (the core) free of any ecosystem dependency: the
+ * plugins live in each package's `/testing` subpath and depend on helix, never
+ * the other way round — the Japa "runner + plugins" topology.
+ */
+import { cliArgs } from "./cli-args.js";
+import { TestContextRegistry } from "./context.js";
+import { emitter } from "./emitter.js";
+import { Runner } from "./runner.js";
+import { makeSuiteHandle, setCurrentSuite, } from "./suite-taps.js";
+/** Build a {@link Refiner} writing into `filters`. */
+function makeRefiner(filters) {
+    return {
+        add(layer, values) {
+            filters[layer] = [...(filters[layer] ?? []), ...values];
+        },
+        matchAllTags(toggle = true) {
+            filters.matchAll = toggle;
+        },
+    };
+}
+/** Teardowns to run after the run — from `configure({ teardown })` + `api.cleanup`. */
+const runnerTeardowns = [];
+/** Undos returned by `setup` hooks — drained BEFORE the teardowns. */
+const runnerCleanups = [];
+const configuredDefaults = {};
+/** The defaults set by {@link configure}, if any. */
+export function getConfiguredDefaults() {
+    return configuredDefaults;
+}
+/** Tracks the run by listening to {@link emitter} — handed to plugins. */
+const runner = new Runner(emitter);
+/** The options the last {@link configure} call resolved to (Japa `config`). */
+let resolvedConfig = {};
+const api = {
+    // A getter so a plugin reads the config of the `configure()` call it is
+    // running under, not an empty object captured at module load. Japa lets a
+    // plugin EDIT it (that is how a plugin raises the default timeout), so the
+    // object is handed over mutable and read back after every plugin has run.
+    get config() {
+        return resolvedConfig;
+    },
+    // The same object every access, for the same reason: a plugin that writes
+    // `api.cliArgs.tags = [...]` must actually steer the run.
+    get cliArgs() {
+        return cliArgs();
+    },
+    runner,
+    emitter,
+    context: {
+        macro: (name, value) => TestContextRegistry.macro(name, value),
+        getter: (name, fn) => TestContextRegistry.getter(name, fn),
+    },
+    cleanup: (fn) => {
+        runnerTeardowns.push(fn);
+    },
+};
+/**
+ * Install plugins + runner hooks. Call once from a bootstrap file
+ * (Japa/AdonisJS `bin/test.ts` / `tests/bootstrap.ts`).
+ *
+ * Order follows Japa: PLUGINS first, then the run's `setup` hooks, then the
+ * `teardown` hooks are parked for after the run (see {@link
+ * drainRunnerTeardowns}). That ordering is what makes a plugin's edits count —
+ * it can raise `config.timeout`, push a `setup` hook, or reach for
+ * `runner.onSuite`, and the run picks all of it up because nothing has been
+ * read yet.
+ */
+export async function configure(options) {
+    resolvedConfig = options;
+    // Hook arrays a plugin can append to (through `runner.onSuite`) — they must
+    // exist before the plugins run, and they are the very arrays drained below.
+    resolvedConfig.setup ??= [];
+    resolvedConfig.teardown ??= [];
+    const setup = resolvedConfig.setup;
+    const teardown = resolvedConfig.teardown;
+    const handle = makeSuiteHandle(options.suite ?? "default", setup, teardown);
+    setCurrentSuite(handle);
+    // The rest of Japa's `BaseConfig`, filled with what this run actually is, so
+    // a plugin reading `api.config` is told the truth rather than `undefined`.
+    const flags = cliArgs();
+    resolvedConfig.cwd ??= process.cwd();
+    resolvedConfig.reporters ??= { activated: flags.reporters ?? [] };
+    resolvedConfig.forceExit ??= flags.forceExit === true;
+    resolvedConfig.filters ??= {};
+    resolvedConfig.filters.files ??= flags.files;
+    resolvedConfig.filters.suites ??=
+        flags.suite === undefined ? undefined : [flags.suite];
+    resolvedConfig.refiner ??= makeRefiner(resolvedConfig.filters);
+    for (const plugin of resolvedConfig.plugins ?? []) {
+        await plugin(api);
+    }
+    // Japa order: plugins, THEN `runner.onSuite(config.configureSuite)`, then the
+    // setup hooks. Applying it here rather than earlier is what lets a plugin
+    // read it — or put its own in place — and still have it take effect.
+    await resolvedConfig.configureSuite?.(handle);
+    // Read the defaults back AFTER the plugins, so a plugin that edited the
+    // config steers the run rather than writing into a value already consumed.
+    if (resolvedConfig.timeout !== undefined)
+        configuredDefaults.timeout = resolvedConfig.timeout;
+    if (resolvedConfig.retries !== undefined)
+        configuredDefaults.retries = resolvedConfig.retries;
+    if (resolvedConfig.suite !== undefined)
+        configuredDefaults.suite = resolvedConfig.suite;
+    if (resolvedConfig.filters !== undefined)
+        configuredDefaults.filters = resolvedConfig.filters;
+    if (resolvedConfig.importer !== undefined)
+        configuredDefaults.importer = resolvedConfig.importer;
+    // Japa skips the global setup hooks under `--list-pinned`: nothing runs, so
+    // nothing should be opened.
+    const listing = cliArgs().listPinned === true;
+    for (const fn of listing ? [] : setup) {
+        // A `setup` hook may resolve to its own undo (the AdonisJS idiom); park it
+        // with the teardowns so it runs in reverse order with everything else.
+        const undo = await fn(runner);
+        if (typeof undo === "function")
+            runnerCleanups.push(undo);
+    }
+    for (const fn of teardown)
+        runnerTeardowns.push(fn);
+}
+/**
+ * Run every registered runner teardown (reverse order), then clear them — called
+ * by the runtime after a file's tests finish. Failures are logged, not thrown,
+ * so one bad teardown can't hide the test results.
+ */
+export async function drainRunnerTeardowns() {
+    // Cleanups returned by `setup` unwind first — they are the innermost thing
+    // that was opened. `null` for the error: the drain only happens once the run
+    // itself has finished, so there is no setup failure left to report.
+    for (let i = runnerCleanups.length - 1; i >= 0; i -= 1) {
+        try {
+            await runnerCleanups[i](null, runner);
+        }
+        catch (err) {
+            console.error("[helix] runner cleanup failed:", err);
+        }
+    }
+    runnerCleanups.length = 0;
+    for (let i = runnerTeardowns.length - 1; i >= 0; i -= 1) {
+        try {
+            await runnerTeardowns[i](runner);
+        }
+        catch (err) {
+            console.error("[helix] runner teardown failed:", err);
+        }
+    }
+    runnerTeardowns.length = 0;
+}
+//# sourceMappingURL=configure.js.map

package/dist/runtime/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../../src/runtime/configure.ts"],"names":[],"mappings":"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"}

package/dist/runtime/context.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Injected test context — Japa's defining mechanism.
+ *
+ * Every test body (and, later, group hooks) receives a `TestContext` as its
+ * FIRST argument: `test("x", ({ assert, client, db, cleanup }) => …)`. The
+ * context is EXTENSIBLE via declaration merging: capability plugins (HTTP
+ * client, DB, fakes) both register a runtime property through
+ * {@link TestContextRegistry} AND augment the `TestContext` interface:
+ *
+ *     declare module "@c9up/helix" {
+ *       interface TestContext { client: ApiClient }
+ *     }
+ *
+ * This is what lets `@c9up/helix/http`, `@c9up/helix/db`, … graft `client`,
+ * `db`, … onto the context — fully typed — without the core depending on those
+ * packages.
+ *
+ * Backwards compatible: passing the context as the first arg is a no-op for
+ * existing zero-argument bodies (`test("x", () => …)`), which ignore it.
+ */
+import { type Assert } from "./assert.js";
+import type { TestInstance } from "./suite.js";
+import { type TestCleanup } from "./test-context.js";
+/**
+ * The per-test context. `cleanup` is always present; capability plugins add
+ * `assert`, `client`, `db`, … by augmenting this interface (declaration
+ * merging) alongside a matching {@link TestContextRegistry} registration.
+ */
+/**
+ * A CLASS (not an interface) so plugins can add REQUIRED properties via
+ * declaration merging — `declare module "@c9up/helix" { interface TestContext {
+ * client: ApiClient } }` — without breaking the core's construction (an external
+ * augmentation is not subject to helix's `strictPropertyInitialization`). This
+ * is exactly how Japa's `TestContext` works.
+ */
+export declare class TestContext {
+    /**
+     * Add a shared property to every test context — Japa's
+     * `TestContext.macro('sleep', fn)`, callable on the class itself so a Japa
+     * plugin's registration code ports over unchanged.
+     */
+    static macro(name: string, value: unknown): void;
+    /** Add a lazily-computed, per-context property (Japa `TestContext.getter`). */
+    static getter(name: string, fn: Getter): void;
+    /** Chai-flavored assertions (`@japa/assert` parity), alongside `expect`. */
+    readonly assert: Assert;
+    /** The running test's own instance — name, options, dataset (Japa `ctx.test`). */
+    readonly test: TestInstance;
+    constructor(test: TestInstance);
+    /**
+     * Register a teardown that runs at the end of THIS test, regardless of
+     * outcome (Japa `ctx.cleanup`). Reverse-insertion order, isolated failures.
+     */
+    cleanup(fn: TestCleanup): void;
+}
+export type Getter = (this: TestContext, ctx: TestContext) => unknown;
+/**
+ * Registry through which plugins extend the test context at runtime. Mirrors
+ * Japa's `TestContext.macro(name, value)` / `TestContext.getter(name, fn)`.
+ * Pair each call with a `declare module` augmentation for the types.
+ */
+export declare const TestContextRegistry: {
+    /** Add a shared property present on every test context. */
+    macro(name: string, value: unknown): void;
+    /**
+     * Add a lazily-computed, per-context property. The getter runs the first
+     * time the property is read on a given context (inside that test's frame),
+     * and the result is cached for that context.
+     */
+    getter(name: string, fn: Getter): void;
+    /** Remove a macro/getter (plugin teardown, tests). No arg clears all. */
+    clear(name?: string): void;
+    /** Whether any extension is registered under `name`. */
+    has(name: string): boolean;
+};
+/**
+ * Build a fresh `TestContext` for one test attempt. MUST be called inside the
+ * per-test frame (`withTestContext`) so `ctx.cleanup` reaches the right frame.
+ * Applies registered macros (own value), then getters (lazy, cached per
+ * context). Dynamic props are attached via `defineProperty` so no `cleanup`
+ * override and no cast are needed.
+ */
+export declare function buildTestContext(test: TestInstance): TestContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/runtime/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;GAIG;AACH;;;;;;GAMG;AACH,qBAAa,WAAW;IACvB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAIhD,+EAA+E;IAC/E,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;gBAEhB,IAAI,EAAE,YAAY;IAK9B;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI;CAK9B;AAID,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;AAKtE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC/B,2DAA2D;gBAC/C,MAAM,SAAS,OAAO,GAAG,IAAI;IAGzC;;;;OAIG;iBACU,MAAM,MAAM,MAAM,GAAG,IAAI;IAGtC,yEAAyE;iBAC5D,MAAM,GAAG,IAAI;IAS1B,wDAAwD;cAC9C,MAAM,GAAG,OAAO;CAG1B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAqChE"}

package/dist/runtime/context.js

@@ -0,0 +1,146 @@
+/**
+ * Injected test context — Japa's defining mechanism.
+ *
+ * Every test body (and, later, group hooks) receives a `TestContext` as its
+ * FIRST argument: `test("x", ({ assert, client, db, cleanup }) => …)`. The
+ * context is EXTENSIBLE via declaration merging: capability plugins (HTTP
+ * client, DB, fakes) both register a runtime property through
+ * {@link TestContextRegistry} AND augment the `TestContext` interface:
+ *
+ *     declare module "@c9up/helix" {
+ *       interface TestContext { client: ApiClient }
+ *     }
+ *
+ * This is what lets `@c9up/helix/http`, `@c9up/helix/db`, … graft `client`,
+ * `db`, … onto the context — fully typed — without the core depending on those
+ * packages.
+ *
+ * Backwards compatible: passing the context as the first arg is a no-op for
+ * existing zero-argument bodies (`test("x", () => …)`), which ignore it.
+ */
+import { createAssert } from "./assert.js";
+import { registerTestCleanup } from "./test-context.js";
+/**
+ * The per-test context. `cleanup` is always present; capability plugins add
+ * `assert`, `client`, `db`, … by augmenting this interface (declaration
+ * merging) alongside a matching {@link TestContextRegistry} registration.
+ */
+/**
+ * A CLASS (not an interface) so plugins can add REQUIRED properties via
+ * declaration merging — `declare module "@c9up/helix" { interface TestContext {
+ * client: ApiClient } }` — without breaking the core's construction (an external
+ * augmentation is not subject to helix's `strictPropertyInitialization`). This
+ * is exactly how Japa's `TestContext` works.
+ */
+export class TestContext {
+    /**
+     * Add a shared property to every test context — Japa's
+     * `TestContext.macro('sleep', fn)`, callable on the class itself so a Japa
+     * plugin's registration code ports over unchanged.
+     */
+    static macro(name, value) {
+        TestContextRegistry.macro(name, value);
+    }
+    /** Add a lazily-computed, per-context property (Japa `TestContext.getter`). */
+    static getter(name, fn) {
+        TestContextRegistry.getter(name, fn);
+    }
+    /** Chai-flavored assertions (`@japa/assert` parity), alongside `expect`. */
+    assert;
+    /** The running test's own instance — name, options, dataset (Japa `ctx.test`). */
+    test;
+    constructor(test) {
+        this.assert = createAssert();
+        this.test = test;
+    }
+    /**
+     * Register a teardown that runs at the end of THIS test, regardless of
+     * outcome (Japa `ctx.cleanup`). Reverse-insertion order, isolated failures.
+     */
+    cleanup(fn) {
+        // Falls through to the active per-test frame; a false return means we were
+        // called outside a frame (defensive — the runner always wraps).
+        registerTestCleanup(fn);
+    }
+}
+const macros = new Map();
+const getters = new Map();
+/**
+ * Registry through which plugins extend the test context at runtime. Mirrors
+ * Japa's `TestContext.macro(name, value)` / `TestContext.getter(name, fn)`.
+ * Pair each call with a `declare module` augmentation for the types.
+ */
+export const TestContextRegistry = {
+    /** Add a shared property present on every test context. */
+    macro(name, value) {
+        macros.set(name, value);
+    },
+    /**
+     * Add a lazily-computed, per-context property. The getter runs the first
+     * time the property is read on a given context (inside that test's frame),
+     * and the result is cached for that context.
+     */
+    getter(name, fn) {
+        getters.set(name, fn);
+    },
+    /** Remove a macro/getter (plugin teardown, tests). No arg clears all. */
+    clear(name) {
+        if (name === undefined) {
+            macros.clear();
+            getters.clear();
+        }
+        else {
+            macros.delete(name);
+            getters.delete(name);
+        }
+    },
+    /** Whether any extension is registered under `name`. */
+    has(name) {
+        return macros.has(name) || getters.has(name);
+    },
+};
+/**
+ * Build a fresh `TestContext` for one test attempt. MUST be called inside the
+ * per-test frame (`withTestContext`) so `ctx.cleanup` reaches the right frame.
+ * Applies registered macros (own value), then getters (lazy, cached per
+ * context). Dynamic props are attached via `defineProperty` so no `cleanup`
+ * override and no cast are needed.
+ */
+export function buildTestContext(test) {
+    const ctx = new TestContext(test);
+    // `cleanup` and `test` are structural — the runtime hands them to the body
+    // and nothing may take their place. `assert` is NOT: helix ships one, and a
+    // project installing `@japa/assert` is asking for that one instead. Refusing
+    // the override left the plugin registered but never reached, which is how
+    // `plugins: [assert()]` could look wired and do nothing.
+    const reserved = new Set(["cleanup", "test"]);
+    for (const [name, value] of macros) {
+        if (reserved.has(name))
+            continue;
+        Object.defineProperty(ctx, name, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    for (const [name, fn] of getters) {
+        if (reserved.has(name))
+            continue;
+        let computed = false;
+        let cached;
+        Object.defineProperty(ctx, name, {
+            enumerable: true,
+            configurable: true,
+            get() {
+                if (!computed) {
+                    cached = fn.call(ctx, ctx);
+                    computed = true;
+                }
+                return cached;
+            },
+        });
+    }
+    return ctx;
+}
+//# sourceMappingURL=context.js.map

package/dist/runtime/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAe,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAoB,MAAM,mBAAmB,CAAC;AAE1E;;;;GAIG;AACH;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACvB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAY,EAAE,KAAc;QACxC,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,MAAM,CAAC,IAAY,EAAE,EAAU;QACrC,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,4EAA4E;IACnE,MAAM,CAAS;IACxB,kFAAkF;IACzE,IAAI,CAAe;IAE5B,YAAY,IAAkB;QAC7B,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,EAAe;QACtB,2EAA2E;QAC3E,gEAAgE;QAChE,mBAAmB,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC;CACD;AAMD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAC;AAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,2DAA2D;IAC3D,KAAK,CAAC,IAAY,EAAE,KAAc;QACjC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IACD;;;;OAIG;IACH,MAAM,CAAC,IAAY,EAAE,EAAU;QAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACvB,CAAC;IACD,yEAAyE;IACzE,KAAK,CAAC,IAAa;QAClB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACpB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACF,CAAC;IACD,wDAAwD;IACxD,GAAG,CAAC,IAAY;QACf,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;CACD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IAClD,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,yDAAyD;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE;YAChC,KAAK;YACL,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,IAAI;SACd,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;QAClC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,MAAe,CAAC;QACpB,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE;YAChC,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,GAAG;gBACF,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACf,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;oBAC3B,QAAQ,GAAG,IAAI,CAAC;gBACjB,CAAC;gBACD,OAAO,MAAM,CAAC;YACf,CAAC;SACD,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/runtime/emitter.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Runner events — the Japa `Emitter` surface.
+ *
+ * Japa's plugin/reporter topology is built on an event emitter: a plugin
+ * receives `{ config, cliArgs, runner, emitter }` and subscribes to
+ * `runner:start`, `suite:start`, `group:start`, `test:start`, … to observe the
+ * run. Helix emits the SAME event names with the SAME node shapes
+ * (`TestStartNode`, `TestEndNode`, `GroupStartNode`, …) so a Japa reporter or
+ * plugin can be ported without rewriting its listeners.
+ *
+ * One named deviation from `@japa/core`: `suite:start` / `suite:end` carry the
+ * test FILE name. Helix runs one process per file, so the file is what a
+ * worker-side listener can see of a suite.
+ *
+ * `errors[].error` is the thrown `Error` itself, as in Japa — the emitter runs
+ * in the worker, where the original is still around. Only an error rebuilt from
+ * an IPC frame (which can carry data only) degrades to the {@link
+ * SerializedError} shape, which keeps the same `name`/`message`/`stack` fields.
+ */
+import type { SerializedError } from "./run.js";
+/** The lifecycle phase an error was raised in (Japa parity). */
+export type ErrorPhase = "setup" | "test" | "setup:cleanup" | "teardown" | "teardown:cleanup" | "test:cleanup";
+/**
+ * One captured failure, tagged with the phase it happened in. `error` is the
+ * thrown `Error`; it degrades to {@link SerializedError} — same `name`,
+ * `message` and `stack` — only for a result rebuilt from an IPC frame.
+ */
+export interface EmittedError {
+    phase: ErrorPhase;
+    error: Error | SerializedError;
+}
+/** A test title, before and after dataset interpolation (Japa parity). */
+export interface EmittedTitle {
+    original: string;
+    expanded: string;
+}
+/** The dataset row a test instance was expanded from. */
+export interface EmittedDataset {
+    size: number;
+    index: number;
+    row: unknown;
+}
+/**
+ * Shared shape of `test:start` / `test:end` — Japa's `TestOptions`, field for
+ * field. Only `title`, `tags`, `timeout`, `meta` and `isPinned` always carry a
+ * value; the rest appear when the corresponding modifier was used, so a
+ * reporter that probes for a key sees what Japa would show it.
+ */
+interface TestNodeBase {
+    title: EmittedTitle;
+    tags: string[];
+    timeout: number;
+    waitsForDone?: boolean;
+    /** The test body, as Japa hands it over. Absent on a `todo`. */
+    executor?: (...args: never[]) => unknown;
+    retries?: number;
+    retryAttempt?: number;
+    isTodo?: boolean;
+    isSkipped?: boolean;
+    isFailing?: boolean;
+    skipReason?: string;
+    failReason?: string;
+    isPinned: boolean;
+    meta: Record<string, unknown>;
+    dataset?: EmittedDataset;
+}
+/** Payload of `test:start`. */
+export type TestStartNode = TestNodeBase;
+/** Payload of `test:end`. */
+export type TestEndNode = TestNodeBase & {
+    duration: number;
+    hasError: boolean;
+    errors: EmittedError[];
+};
+/** Payload of `group:start`. */
+export interface GroupStartNode {
+    title: string;
+    meta: Record<string, unknown>;
+}
+/** Payload of `group:end`. */
+export type GroupEndNode = GroupStartNode & {
+    hasError: boolean;
+    errors: EmittedError[];
+};
+/** Payload of `suite:start` — helix's suite is the test file. */
+export interface SuiteStartNode {
+    name: string;
+}
+/** Payload of `suite:end`. */
+export type SuiteEndNode = SuiteStartNode & {
+    hasError: boolean;
+    errors: EmittedError[];
+};
+/**
+ * Payload of `runner:start`. Japa types this as `{}`; helix spells the same
+ * "no fields" shape as an empty record so no lint suppression is needed.
+ */
+export type RunnerStartNode = Record<string, never>;
+/** Payload of `runner:end`. */
+export interface RunnerEndNode {
+    hasError: boolean;
+}
+/** Every event the runtime emits, with its payload (Japa `RunnerEvents`). */
+export interface RunnerEvents {
+    "test:start": TestStartNode;
+    "test:end": TestEndNode;
+    "group:start": GroupStartNode;
+    "group:end": GroupEndNode;
+    "suite:start": SuiteStartNode;
+    "suite:end": SuiteEndNode;
+    "runner:start": RunnerStartNode;
+    "runner:end": RunnerEndNode;
+}
+/** A listener for one event. */
+export type EventHandler<E extends keyof RunnerEvents> = (payload: RunnerEvents[E]) => void;
+/**
+ * A typed event emitter over {@link RunnerEvents}. Deliberately minimal — `on`
+ * / `once` / `off` / `emit`, the surface a Japa reporter or plugin uses. A
+ * throwing listener is reported on stderr and never fails the run.
+ */
+export declare class Emitter {
+    #private;
+    /** Subscribe to an event. Returns `this` for chaining. */
+    on<E extends keyof RunnerEvents>(event: E, handler: EventHandler<E>): this;
+    /** Subscribe to the next occurrence of an event only. */
+    once<E extends keyof RunnerEvents>(event: E, handler: EventHandler<E>): this;
+    /** Remove a previously registered listener. */
+    off<E extends keyof RunnerEvents>(event: E, handler: EventHandler<E>): this;
+    /** Drop every listener (used between runs in the same process). */
+    clear(): void;
+    /** Broadcast an event. Listener failures are isolated. */
+    emit<E extends keyof RunnerEvents>(event: E, payload: RunnerEvents[E]): void;
+}
+/**
+ * The process-wide emitter. Helix runs one file per process, so a module-level
+ * instance is the run's emitter — the same object plugins receive at
+ * `configure()` time and the runtime emits on.
+ */
+export declare const emitter: Emitter;
+export {};
+//# sourceMappingURL=emitter.d.ts.map

package/dist/runtime/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/runtime/emitter.ts"],"names":[],"mappings":"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"}

package/dist/runtime/emitter.js

@@ -0,0 +1,79 @@
+/**
+ * Runner events — the Japa `Emitter` surface.
+ *
+ * Japa's plugin/reporter topology is built on an event emitter: a plugin
+ * receives `{ config, cliArgs, runner, emitter }` and subscribes to
+ * `runner:start`, `suite:start`, `group:start`, `test:start`, … to observe the
+ * run. Helix emits the SAME event names with the SAME node shapes
+ * (`TestStartNode`, `TestEndNode`, `GroupStartNode`, …) so a Japa reporter or
+ * plugin can be ported without rewriting its listeners.
+ *
+ * One named deviation from `@japa/core`: `suite:start` / `suite:end` carry the
+ * test FILE name. Helix runs one process per file, so the file is what a
+ * worker-side listener can see of a suite.
+ *
+ * `errors[].error` is the thrown `Error` itself, as in Japa — the emitter runs
+ * in the worker, where the original is still around. Only an error rebuilt from
+ * an IPC frame (which can carry data only) degrades to the {@link
+ * SerializedError} shape, which keeps the same `name`/`message`/`stack` fields.
+ */
+/**
+ * A typed event emitter over {@link RunnerEvents}. Deliberately minimal — `on`
+ * / `once` / `off` / `emit`, the surface a Japa reporter or plugin uses. A
+ * throwing listener is reported on stderr and never fails the run.
+ */
+export class Emitter {
+    #listeners = new Map();
+    /** Subscribe to an event. Returns `this` for chaining. */
+    on(event, handler) {
+        const set = this.#listeners.get(event) ?? new Set();
+        set.add({ fn: handler });
+        this.#listeners.set(event, set);
+        return this;
+    }
+    /** Subscribe to the next occurrence of an event only. */
+    once(event, handler) {
+        const wrapped = (payload) => {
+            this.off(event, wrapped);
+            handler(payload);
+        };
+        return this.on(event, wrapped);
+    }
+    /** Remove a previously registered listener. */
+    off(event, handler) {
+        const set = this.#listeners.get(event);
+        if (set === undefined)
+            return this;
+        for (const entry of set) {
+            if (entry.fn === handler)
+                set.delete(entry);
+        }
+        return this;
+    }
+    /** Drop every listener (used between runs in the same process). */
+    clear() {
+        this.#listeners.clear();
+    }
+    /** Broadcast an event. Listener failures are isolated. */
+    emit(event, payload) {
+        const set = this.#listeners.get(event);
+        if (set === undefined)
+            return;
+        // Snapshot: a `once` listener removes itself while we iterate.
+        for (const entry of [...set]) {
+            try {
+                entry.fn(payload);
+            }
+            catch (err) {
+                console.error(`[helix] "${event}" listener failed:`, err);
+            }
+        }
+    }
+}
+/**
+ * The process-wide emitter. Helix runs one file per process, so a module-level
+ * instance is the run's emitter — the same object plugins receive at
+ * `configure()` time and the runtime emits on.
+ */
+export const emitter = new Emitter();
+//# sourceMappingURL=emitter.js.map

package/dist/runtime/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/runtime/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmIH;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACV,UAAU,GAAG,IAAI,GAAG,EAA2C,CAAC;IAEzE,0DAA0D;IAC1D,EAAE,CAA+B,KAAQ,EAAE,OAAwB;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,EAAkB,CAAC;QACpE,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,yDAAyD;IACzD,IAAI,CAA+B,KAAQ,EAAE,OAAwB;QACpE,MAAM,OAAO,GAAoB,CAAC,OAAO,EAAE,EAAE;YAC5C,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACzB,OAAO,CAAC,OAAO,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,+CAA+C;IAC/C,GAAG,CAA+B,KAAQ,EAAE,OAAwB;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YACzB,IAAI,KAAK,CAAC,EAAE,KAAK,OAAO;gBAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,mEAAmE;IACnE,KAAK;QACJ,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED,0DAA0D;IAC1D,IAAI,CAA+B,KAAQ,EAAE,OAAwB;QACpE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAC9B,+DAA+D;QAC/D,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACJ,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,oBAAoB,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;QACF,CAAC;IACF,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC"}