@noego/testing 0.1.0 → 0.4.0

package/dist/index.d.ts

@@ -1,262 +1,318 @@
-import { Clock, Instant, Duration, Scheduler, ScheduleInput, ScheduledTaskHandle, ScheduledTaskId, IdGenerator, BrandedId, RandomSource, FetchRequest, FetchResponse, FetchError, FetchClient, ProcessCommand, ProcessEvent, ProcessRunner, ProcessResult, SpawnCommand, ProcessHandle, KeyValueStore, Key, Codec, PutOptions, ObjectStore, ObjectKey, StoredObject, StoredObjectInput, ObjectVersion, DomainEvent, EventBus, EventHandler, Subscription, LogSink, LogEnvelope, TelemetrySink, TelemetryEnvelope, TraceSink, TraceEnvelope } from '@noego/runtime';
+import { IContainer, ApplicationModule } from '@noego/ioc';
 
 /**
- * Deterministic clock. Time never moves unless the test moves it.
- * Defaults to a fixed instant so snapshots are stable.
+ * Lowercase `test.*` descriptors — immutable frozen values.
+ *
+ * Descriptors carry NO mutable state (no cursors, no counters, no histories);
+ * all mutable invocation state lives in the built environment, so one
+ * descriptor value is safe to share across builders and repeated builds.
  */
-declare class ManualClock extends Clock {
-    static readonly defaultStart: Instant;
-    private current;
-    constructor(start?: Instant);
-    now(): Instant;
-    set(instant: Instant): void;
-    advanceBy(duration: Duration): void;
+declare const DESCRIPTOR: unique symbol;
+/** A raw custom method wrapper: (original) => replacement. NOT auto-watched. */
+type RawMethodWrapper = (original: (...args: any[]) => any) => (...args: any[]) => any;
+interface ReturnsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'returns';
+    readonly value: unknown;
 }
-
-interface PendingTask {
-    readonly id: ScheduledTaskId;
-    readonly label: string;
-    readonly deadline: Instant;
+interface ThrowsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'throws';
+    readonly error: unknown;
 }
-/**
- * Deterministic scheduler driven by a ManualClock.
- *
- * Locked semantics:
- * - deadlines are (scheduledAt + delay);
- * - equal deadlines run in insertion order;
- * - cancelled tasks never execute;
- * - callbacks scheduled by callbacks are ordered deterministically (insertion
- *   sequence is global and monotonic);
- * - async callbacks settle before advancing continues;
- * - runUntilIdle fails with a bounded diagnostic on infinite reschedule loops;
- * - assertNoPendingTasks fails teardown when tasks remain, unless allowed;
- * - CHOSEN MODEL: advancing time RUNS every task whose deadline falls inside
- *   the advanced window, in deadline order. advanceBy(Duration.zero) runs
- *   tasks already due.
- */
-declare class ManualScheduler extends Scheduler {
-    private readonly clock;
-    private readonly tasks;
-    private nextSequence;
-    private nextId;
-    constructor(clock: ManualClock);
-    schedule(input: ScheduleInput): ScheduledTaskHandle;
-    pending(): PendingTask[];
-    /** Advance the clock, running every task due inside the window in order. */
-    advanceBy(duration: Duration): Promise<void>;
-    /** Advance to the earliest pending deadline and run exactly that task. */
-    runNext(): Promise<void>;
-    /** Run tasks (advancing time as needed) until none remain. */
-    runUntilIdle(options?: {
-        maxTasks?: number;
-    }): Promise<void>;
-    /** Teardown assertion: fails when pending tasks remain, unless allowed. */
-    assertNoPendingTasks(options?: {
-        allow?: boolean;
-    }): void;
-    private live;
-    private nextDue;
-    private execute;
-    private remove;
+interface OriginalDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'original';
 }
-
-/**
- * Deterministic ID generator: "<brand>-1", "<brand>-2", … per brand.
- * Fixed IDs keep snapshots stable; isolation makes collisions impossible.
- */
-declare class SequenceIdGenerator extends IdGenerator {
-    private readonly counters;
-    next<TBrand extends string>(brand: TBrand): BrandedId<TBrand>;
+interface CallsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'calls';
+    readonly script: readonly BehaviorDescriptor[];
 }
-
-/**
- * Deterministic random source (mulberry32). The same seed always yields the
- * same sequence.
- */
-declare class SeededRandomSource extends RandomSource {
-    private state;
-    constructor(seed?: number);
-    private nextUint32;
-    bytes(length: number): Uint8Array;
-    integer(minInclusive: number, maxExclusive: number): number;
+type BehaviorDescriptor = ReturnsDescriptor | ThrowsDescriptor | OriginalDescriptor | CallsDescriptor;
+interface WatchDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'watch';
+    readonly wrapper?: RawMethodWrapper;
 }
-
-interface FetchScriptEntry {
-    /** Human-readable description used in failure diagnostics. */
-    readonly describe: string;
-    /** Typed predicate the incoming request must satisfy. */
-    readonly matches: (request: FetchRequest) => boolean;
-    /** Either respond or fail with a normalized FetchError. */
-    readonly respond: (request: FetchRequest) => FetchResponse | FetchError;
+interface ExpectationDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'expect';
+    /** Exact required call count; 0 for never(). */
+    readonly expected: number;
+    /** Behavior used for allowed calls; undefined = original effective behavior. */
+    readonly behavior?: BehaviorDescriptor;
+}
+/** Everything installable through .methods({...}). */
+type MethodDescriptor = BehaviorDescriptor | WatchDescriptor | ExpectationDescriptor | RawMethodWrapper;
+declare const test: {
+    /** Return the supplied value when the method is called. Auto-watches. */
+    returns(value: unknown): ReturnsDescriptor;
+    /** Throw/reject with the supplied error. Auto-watches. */
+    throws(error: unknown): ThrowsDescriptor;
+    /** Invoke the original effective method. Auto-watches. */
+    original(): OriginalDescriptor;
+    /**
+     * Per-invocation behavior script: call 1 uses entry 1, and so on. A call
+     * after exhaustion fails immediately. Unused entries do not fail verification.
+     */
+    calls(script: readonly BehaviorDescriptor[]): CallsDescriptor;
+    /**
+     * Keep original behavior and record calls. With a raw wrapper argument, the
+     * wrapper's behavior runs and is recorded.
+     */
+    watch(wrapper?: RawMethodWrapper): WatchDescriptor;
+    /** Require exactly one call; with no behavior, the original runs. */
+    once(behavior?: BehaviorDescriptor): ExpectationDescriptor;
+    /** Require exactly `count` calls; with no behavior, the original runs. */
+    times(count: number, behavior?: BehaviorDescriptor): ExpectationDescriptor;
+    /** Require zero calls; the first invocation fails and skips the original. */
+    never(): ExpectationDescriptor;
+    /** Read the recorded history for a watched method in one environment. */
+    inspect(environment: unknown, token: unknown, method: string): MethodInspection;
+};
+/** Symbol under which a built environment exposes its watch registry. */
+declare const ENV_REGISTRY: unique symbol;
+interface RecordedCall {
+    /** 1-based invocation index in this environment. */
+    readonly index: number;
+    readonly args: readonly unknown[];
+    /** Present once the call returned (resolved value for async methods). */
+    readonly result?: unknown;
+    /** Present once the call threw/rejected. */
+    readonly error?: unknown;
+    /** True while an async outcome is still pending. */
+    readonly pending: boolean;
+    readonly timestamp: number;
+}
+interface MethodInspection {
+    readonly count: number;
+    readonly calls: readonly RecordedCall[];
 }
+
 /**
- * Scripted FetchClient. Scripts are consumed strictly in order; an unexpected
- * or mismatched call fails immediately with a diagnostic.
+ * Environment-owned method behavior/observation runtime.
+ *
+ * All mutable state (histories, expectation counters, calls-script cursors)
+ * lives here, created fresh at every build(). Descriptors stay immutable.
  */
-declare class ScriptedFetchClient extends FetchClient {
-    private readonly script;
-    private cursor;
-    readonly executed: FetchRequest[];
-    constructor(script: readonly FetchScriptEntry[]);
-    execute(request: FetchRequest): Promise<FetchResponse>;
-    /** Teardown assertion: every scripted call must have been consumed. */
-    assertScriptConsumed(): void;
-}
 
-/** Spawn handle with test-only deterministic delivery control. */
-interface ScriptedSpawnHandle extends ProcessHandle {
-    /** Deliver all scripted events now (deterministic, test-controlled). */
-    flush(): void;
+interface MutableCall {
+    index: number;
+    args: readonly unknown[];
+    result?: unknown;
+    error?: unknown;
+    pending: boolean;
+    timestamp: number;
 }
-interface ProcessScriptEntry {
-    readonly describe: string;
-    readonly matches: (command: ProcessCommand) => boolean;
-    /** Events emitted (for spawn) / folded into the result (for run). */
-    readonly events: readonly ProcessEvent[];
+declare class MethodState {
+    readonly tokenName: string;
+    readonly method: string;
+    readonly descriptor: Exclude<MethodDescriptor, RawMethodWrapper>;
+    readonly calls: MutableCall[];
+    /** Actual invocation count (includes the call currently executing). */
+    actual: number;
+    /** Cursor into a test.calls() script. */
+    scriptCursor: number;
+    constructor(tokenName: string, method: string, descriptor: Exclude<MethodDescriptor, RawMethodWrapper>);
+    get expectation(): ExpectationDescriptor | undefined;
+    inspection(): MethodInspection;
 }
-/**
- * Scripted ProcessRunner. Scripts are consumed in order; unexpected commands
- * fail immediately. Spawned handles emit their declared events when
- * flush() is called, keeping delivery under test control.
- */
-declare class ScriptedProcessRunner extends ProcessRunner {
-    private readonly script;
-    private cursor;
-    private readonly openHandles;
-    constructor(script: readonly ProcessScriptEntry[]);
-    private consume;
-    run(command: ProcessCommand): Promise<ProcessResult>;
-    spawn(command: SpawnCommand): ScriptedSpawnHandle;
-    /** Teardown assertion: no spawned process may remain open. */
-    assertNoOpenHandles(): void;
+/** One method-config entry: how it was keyed, and its per-method descriptors. */
+interface MethodConfigEntry {
+    /** Exact token (class/symbol/string) or a name string matched lazily. */
+    readonly key: unknown;
+    readonly byName: boolean;
+    readonly methods: ReadonlyMap<string, MethodDescriptor>;
+}
+declare class WatchRegistry {
+    /** entry-identity → method → state. Entries share states across instances. */
+    private readonly states;
+    private readonly nameIndex;
+    private readonly entries;
+    /** Class-token entries that identity-matched at least one construction. */
+    private readonly matchedEntryKeys;
+    /** Constructed class tokens that matched NO entry, by display name. */
+    private readonly unmatchedConstructedByName;
+    addEntry(entry: MethodConfigEntry): void;
+    private entryLabel;
+    /** Entries applying to a resolving token (exact identity or name match). */
+    matchEntries(token: unknown): MethodConfigEntry[];
+    state(entryKey: unknown, method: string): MethodState | undefined;
+    inspect(token: unknown, method: string): MethodInspection;
+    /**
+     * Class-token entries that never identity-matched a construction while a
+     * DIFFERENT class with the same display name did construct. This is the
+     * split-module-registry signature (a test-file class object vs the graph's
+     * own load of the same file) — or two genuinely distinct same-named tokens
+     * where the configured one never resolved. Either way the configured
+     * behavior silently did not apply, which must be loud.
+     */
+    private identitySplits;
+    /** Repeatable snapshot check of all exact expectations. */
+    verify(): void;
 }
 
 /**
- * Deterministic in-memory KeyValueStore with clock-driven TTL semantics.
- * Passes the same contract as KV/Redis adapters.
+ * `testIoc` — the canonical shared real-IoC test composition builder.
+ *
+ * Persistent immutable: every fluent call returns a new derived builder
+ * sharing the ordered write log structurally. Non-conflicting writes are
+ * order-insensitive; the last write to the same effective identity wins on
+ * that derived branch. `.build()` is non-consuming and creates fresh runtime,
+ * watch, and expectation state (spec 15, PBR-01..15).
  */
-declare class MemoryKeyValueStore extends KeyValueStore {
-    private readonly clock;
-    private readonly entries;
-    constructor(clock: Clock);
-    get<T>(key: Key, codec: Codec<T>): Promise<T | null>;
-    put<T>(key: Key, value: T, codec: Codec<T>, options?: PutOptions): Promise<void>;
-    delete(key: Key): Promise<void>;
-}
 
+type Token = unknown;
+type ClassLike = new (...args: any[]) => any;
+/** Config maps accept plain objects (string keys) or Maps (exact tokens). */
 /**
- * Deterministic in-memory ObjectStore with monotonically increasing versions.
- * Passes the same contract as R2/S3 adapters.
+ * Composition input (spec 04 §2). The CANONICAL entry form is an array of
+ * tuples — token-first, exact identity:
+ *
+ *   .classes([[ProjectRepository, MemoryProjectRepository]])
+ *
+ * A `ReadonlyMap<Token, V>` is equivalent (token-keyed). A name-keyed
+ * `Record<string, V>` remains accepted as COMPATIBILITY input: string keys
+ * resolve against known token display names, fail on unknown names, and
+ * fail on ambiguous names (two tokens sharing one display name never
+ * collapse into one entry — tokens are identities, names are labels).
  */
-declare class MemoryObjectStore extends ObjectStore {
-    private readonly objects;
-    private nextVersion;
-    read(key: ObjectKey): Promise<StoredObject | null>;
-    write(key: ObjectKey, object: StoredObjectInput): Promise<ObjectVersion>;
-    delete(key: ObjectKey): Promise<void>;
+type ConfigMap<V> = ReadonlyArray<readonly [Token, V]> | ReadonlyMap<Token, V> | Record<string, V>;
+type MethodsConfig = ConfigMap<Record<string, MethodDescriptor> | ReadonlyMap<string, MethodDescriptor>>;
+type UseInput = ApplicationModule | TestIocBuilder;
+type Write = {
+    op: 'use';
+    module: ApplicationModule;
+} | {
+    op: 'classes';
+    key: Token;
+    byName: boolean;
+    implementation: ClassLike;
+} | {
+    op: 'functions';
+    key: Token;
+    byName: boolean;
+    factory: (...args: any[]) => any;
+} | {
+    op: 'values';
+    key: Token;
+    byName: boolean;
+    value: unknown;
+} | {
+    op: 'methods';
+    key: Token;
+    byName: boolean;
+    methods: ReadonlyMap<string, MethodDescriptor>;
+};
+interface TestEnvironment {
+    readonly root: IContainer;
+    get<T>(token: unknown, params?: any[]): Promise<T> | T;
+    instance<T>(cls: new (...args: any[]) => T, params?: any[]): Promise<T> | T;
+    extend(): IContainer;
+    verify(): Promise<void>;
+    dispose(): Promise<void>;
+    readonly [ENV_REGISTRY]: WatchRegistry;
 }
+declare class TestIocBuilder {
+    private readonly log;
+    private constructor();
+    /** @internal */
+    static create(inputs: readonly UseInput[]): TestIocBuilder;
+    /** @internal — read by .use(builderPreset) */
+    get writes(): readonly Write[];
+    private derive;
+    private useAll;
+    /** Apply a reusable composition preset: an ApplicationModule or a builder. */
+    use(preset: UseInput): TestIocBuilder;
+    /** Replace the implementation for IoC class tokens in the built environment. */
+    classes(config: ConfigMap<ClassLike>): TestIocBuilder;
+    /** Replace IoC factory/provider registrations. */
+    functions(config: ConfigMap<(...args: any[]) => any>): TestIocBuilder;
+    /** Provide/replace IoC value registrations. */
+    values(config: ConfigMap<unknown>): TestIocBuilder;
+    /** Install method behavior/observation descriptors on IoC-managed instances. */
+    methods(config: MethodsConfig): TestIocBuilder;
+    /** Materialize a fresh, isolated real-IoC environment. Non-consuming. */
+    build(): Promise<TestEnvironment>;
+    /**
+     * Register a class binding. When token === implementation this is a plain
+     * class registration. Otherwise an alias factory resolves the implementation
+     * through real IoC, mirroring the implementation's effective lifetime so
+     * lifetime validation (captive-lifetime checks) stays honest.
+     */
+    private registerClassBinding;
+}
+/** Create a persistent immutable real-IoC test composition builder. */
+declare function testIoc(...inputs: UseInput[]): TestIocBuilder;
 
-type DeliveryMode = "immediate" | "queued";
 /**
- * Recording EventBus. Records exact publication order. Delivery modes:
- * - immediate (default): handlers run during publish;
- * - queued: events buffer until deliverQueued() is called.
- * Active subscriptions at teardown fail assertNoActiveSubscriptions().
+ * Diagnostics are first-class: every error names the real token/method and
+ * what was expected vs what happened, never only internal wrapper machinery.
  */
-declare class RecordingEventBus<TEvent extends DomainEvent> extends EventBus<TEvent> {
-    private readonly mode;
-    readonly published: TEvent[];
-    private readonly handlers;
-    private readonly queue;
-    constructor(mode?: DeliveryMode);
-    publish(event: TEvent): Promise<void>;
-    subscribe(handler: EventHandler<TEvent>): Subscription;
-    /** Deliver buffered events (queued mode) in publication order. */
-    deliverQueued(): Promise<void>;
-    get activeSubscriptionCount(): number;
-    assertNoActiveSubscriptions(): void;
-    private deliver;
+declare class TestingError extends Error {
+    constructor(message: string);
 }
-
-/** In-memory LogSink recording envelopes in emission order. */
-declare class RecordingLogSink extends LogSink {
-    readonly envelopes: LogEnvelope[];
-    emit(envelope: LogEnvelope): void;
+/** Thrown at build() when the installed @noego/ioc lacks the decoration seam. */
+declare class MissingIocSeamError extends TestingError {
+    constructor();
 }
-/** In-memory TraceSink recording envelopes in emission order. */
-declare class RecordingTraceSink extends TraceSink {
-    readonly envelopes: TraceEnvelope[];
-    emit(envelope: TraceEnvelope): void;
+/** test.inspect() on a method that is not watched in this environment. */
+declare class UnwatchedInspectionError extends TestingError {
+    constructor(token: string, method: string);
 }
-/** In-memory TelemetrySink recording envelopes in emission order. */
-declare class RecordingTelemetrySink extends TelemetrySink {
-    readonly envelopes: TelemetryEnvelope[];
-    emit(envelope: TelemetryEnvelope): void;
+/** A call arrived after a test.calls([...]) script was fully consumed. */
+declare class CallScriptExhaustedError extends TestingError {
+    constructor(token: string, method: string, scriptLength: number, callIndex: number);
 }
-/** LogSink that drops everything (for suites that assert nothing about logs). */
-declare class NoopLogSink extends LogSink {
-    emit(_envelope: LogEnvelope): void;
+/** An exact expectation (once/times/never) was exceeded at call time. */
+declare class ExpectationOverflowError extends TestingError {
+    constructor(token: string, method: string, expected: number, attempted: number);
 }
-
-/**
- * Behavioral contract every Clock implementation must satisfy.
- * Runs inside the caller's jest context.
- */
-declare function runClockContract(name: string, setup: () => {
-    clock: Clock;
-}): void;
-
-interface KeyValueStoreContractContext {
-    store: KeyValueStore;
-    /** Move the store's time source forward (real adapters may wait/mock). */
-    advanceBy: (duration: Duration) => Promise<void>;
-    /** Whether the implementation supports TTL expiry. */
-    supportsTtl: boolean;
+/** Aggregated under-count failures reported by env.verify(). */
+declare class VerificationError extends TestingError {
+    constructor(failures: readonly {
+        token: string;
+        method: string;
+        expected: number;
+        actual: number;
+    }[]);
 }
-/**
- * Behavioral contract every KeyValueStore implementation must satisfy —
- * memory, KV, and Redis adapters alike.
- */
-declare function runKeyValueStoreContract(name: string, setup: () => KeyValueStoreContractContext): void;
-
-/**
- * Behavioral contract every ObjectStore implementation must satisfy —
- * memory, R2, S3, and filesystem adapters alike.
- */
-declare function runObjectStoreContract(name: string, setup: () => {
-    store: ObjectStore;
-}): void;
-
-interface TestEvent extends DomainEvent {
-    readonly type: "test-event";
-    readonly value: number;
+/** .methods configured for a token whose resolved value has no such callable method. */
+declare class MethodNotCallableError extends TestingError {
+    constructor(token: string, method: string);
+}
+/** .methods configured for a token that resolved to a non-object value. */
+declare class NonObjectMethodTargetError extends TestingError {
+    constructor(token: string);
 }
-declare const testEvent: (value: number) => TestEvent;
-interface EventBusContractContext {
-    bus: EventBus<TestEvent>;
-    /** Force delivery of any buffered events (no-op for immediate buses). */
-    deliver: () => Promise<void>;
+/** A string configuration key could not be resolved to a known IoC token. */
+declare class UnknownTokenKeyError extends TestingError {
+    constructor(key: string, space: string, known: readonly string[]);
+}
+/** Invalid descriptor construction (e.g. test.times(-1)). */
+declare class InvalidDescriptorError extends TestingError {
 }
 /**
- * Behavioral contract every EventBus implementation must satisfy.
+ * A name-keyed compatibility entry referred to a display name claimed by
+ * two or more distinct tokens. Tokens are identities; names are labels —
+ * pass the exact token in canonical tuple form instead (spec 04 §5).
  */
-declare function runEventBusContract(name: string, setup: () => EventBusContractContext): void;
-
-interface LeakCheck {
-    /** Which resource family this check guards (timers, subscriptions, …). */
-    readonly name: string;
-    /** Returns a description per leaked resource; empty means clean. */
-    readonly check: () => readonly string[];
+declare class AmbiguousNameKeyError extends TestingError {
+    constructor(name: string, space: string);
 }
 /**
- * Aggregates leak checks and fails teardown with one clear report listing
- * every leaked resource across all registered checks.
+ * A .methods() class token never matched any constructed instance while a
+ * DIFFERENT class with the same display name did construct — the configured
+ * behavior silently did not apply. Usual cause: two module registries loaded
+ * the same source file (e.g. a vitest test file's import vs a framework
+ * harness's native import of the production graph); fix by routing the
+ * harness's imports through the caller's registry (testApp:
+ * `.importer((p) => import(p))`) or by passing the token the graph actually
+ * uses.
  */
-declare class LeakDetector {
-    private readonly checks;
-    register(check: LeakCheck): void;
-    findLeaks(): string[];
-    assertNoLeaks(): void;
+declare class TokenIdentitySplitError extends TestingError {
+    constructor(names: readonly string[]);
 }
 
-export { type DeliveryMode, type EventBusContractContext, type FetchScriptEntry, type KeyValueStoreContractContext, type LeakCheck, LeakDetector, ManualClock, ManualScheduler, MemoryKeyValueStore, MemoryObjectStore, NoopLogSink, type PendingTask, type ProcessScriptEntry, RecordingEventBus, RecordingLogSink, RecordingTelemetrySink, RecordingTraceSink, ScriptedFetchClient, ScriptedProcessRunner, type ScriptedSpawnHandle, SeededRandomSource, SequenceIdGenerator, type TestEvent, runClockContract, runEventBusContract, runKeyValueStoreContract, runObjectStoreContract, testEvent };
+export { AmbiguousNameKeyError, type BehaviorDescriptor, CallScriptExhaustedError, type CallsDescriptor, type ConfigMap, ENV_REGISTRY, type ExpectationDescriptor, ExpectationOverflowError, InvalidDescriptorError, type MethodDescriptor, type MethodInspection, MethodNotCallableError, type MethodsConfig, MissingIocSeamError, NonObjectMethodTargetError, type OriginalDescriptor, type RawMethodWrapper, type RecordedCall, type ReturnsDescriptor, type TestEnvironment, TestIocBuilder, TestingError, type ThrowsDescriptor, TokenIdentitySplitError, UnknownTokenKeyError, UnwatchedInspectionError, type UseInput, VerificationError, type WatchDescriptor, test, testIoc };