@struktoai/mirage-core/dist/vfs/testing.d.ts

A Unified Virtual Filesystem For AI Agents

import type { IndexCacheStore } from '../cache/index/store.ts';
import type { ConditionMode, WriteKind } from '../cache/types.ts';
import { PathSpec } from '../types.ts';
import type { BaseVFS } from './base.ts';
/** A known file, its parent and absent sibling, and an optional chunk bound. */
export interface ReadFixture {
    file: PathSpec;
    directory: PathSpec;
    missing: PathSpec;
    content: Uint8Array;
    maxChunkSize?: number;
}
/**
 * Verify a VFS's reads against a caller-owned fixture, mutating nothing.
 *
 * A read runs the renderer of the file's filetype where the VFS renders
 * one, else `read`; a read that answers a stream is collected, each chunk
 * held to the fixture's bound, and a missing file may fail when it is called
 * or at its first pull. An existence check is probed only where the VFS
 * defines one. A renderer is always handed a byte window, `read` only where
 * it takes one natively: the caller reads whole and slices otherwise. `index` is the store every function is
 * handed, a RAM store at the VFS's `indexTtl` by default. Mirrors Python's
 * `check_read_contract`.
 */
export declare function checkReadContract(vfs: BaseVFS, fixture: ReadFixture, index?: IndexCacheStore): Promise<void>;
/**
 * An empty, caller-owned scratch directory the check writes its files in,
 * and the bytes it seeds them with. Mirrors Python's `MutationFixture`.
 */
export interface MutationFixture {
    directory: PathSpec;
    content?: Uint8Array;
}
/**
 * Run `fn` under the write context a `write: conditional` mount of `vfs`
 * binds, its cache holding `versions`.
 *
 * Each pair is a path and the version a session read there, null for a
 * path it found no file at. A write, copy or delete of a listed path then
 * carries the condition `conditionSupport` declares for it: `match` on the
 * version, `absent` on null; an unlisted path goes out unconditioned.
 * Mirrors Python's `run_with_versions`.
 */
export declare function runWithVersions<T>(vfs: BaseVFS, versions: readonly (readonly [PathSpec, string | null])[], fn: () => Promise<T>): Promise<T>;
/**
 * Verify a VFS's single-file mutations in an empty, caller-owned scratch
 * directory, unlinking the files it wrote there, pass or fail.
 *
 * Each op is handed the rows a mount reads for it, fresh, as
 * `checkReadContract` hands them. Write preconditions are checked exactly as
 * `conditionSupport` declares them, each op run through `runWithVersions` as
 * a `write: conditional` mount runs it: a declared condition lands when it
 * holds and rejects as a stale write, writing nothing, when it does not. An
 * undeclared condition is refused by the mount before the VFS sees it, so it
 * is not probed. `rename` and `copy` are checked where the VFS defines them:
 * onto a fresh name and over an existing file the destination holds the
 * source's bytes, `rename` removes the source and `copy` keeps it, and a
 * missing source rejects ENOENT and leaves the destination. `index` is the
 * store every function is handed, a RAM store at the VFS's `indexTtl` by
 * default. `unenforced` names declared conditions the backend under test
 * cannot enforce (a fake), each skipped with a warning; naming an undeclared
 * one fails. Mirrors Python's `check_mutation_contract`.
 */
export declare function checkMutationContract(vfs: BaseVFS, fixture: MutationFixture, index?: IndexCacheStore, unenforced?: readonly (readonly [WriteKind, ConditionMode])[]): Promise<void>;
//# sourceMappingURL=testing.d.ts.map