@vibe-agent-toolkit/utils 0.2.0-rc.1 → 0.2.0-rc.10

package/dist/testing/temp-dir.js

@@ -0,0 +1,363 @@
+/**
+ * The ONE temp-directory helper family.
+ *
+ * Every shape a suite needs to mint scratch space lives here: a per-call
+ * `createTempDir`, a tracker that removes what it minted, and the per-suite
+ * sync/async suite helpers with their bounded teardown. The audit counted
+ * eleven definitions of "give me a temp dir that cleans itself up" across
+ * eight modules, six of them named differently and none of them visible to
+ * the duplication gate; this module is where they were collapsed to.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: nothing here imports
+ * `vitest`, so the `./testing` subpath keeps the empty third-party set its
+ * purity pin asserts. Each suite owns its own hooks and calls these from
+ * inside them.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import fs, { mkdtemp } from 'node:fs/promises';
+import { isUnderRoot } from '../path-containment.js';
+import { mkdirSyncReal, normalizedTmpdir, safePath } from '../path-utils.js';
+/**
+ * Mint a fresh temp directory under the host's (short-name-resolved) tmpdir.
+ *
+ * The one-liner that used to be spelled in three packages as
+ * `createTestTempDir`. Pair with {@link removeTempDir}, or let
+ * {@link tempDirTracker} pair them for you.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @returns Absolute, forward-slashed path of the new directory
+ */
+export function createTempDir(prefix) {
+    return safePath.resolve(mkdtempSync(safePath.join(normalizedTmpdir(), prefix)));
+}
+/** The async counterpart of {@link createTempDir}, for suites already on `fs/promises`. */
+export async function createTempDirAsync(prefix) {
+    return safePath.resolve(await mkdtemp(safePath.join(normalizedTmpdir(), prefix)));
+}
+/**
+ * Remove a directory {@link createTempDir} minted — and ONLY such a directory.
+ *
+ * Refuses, by name, to remove anything that is not strictly under the host
+ * tmpdir as the filesystem sees it. A teardown is the one place test code
+ * runs `rm -rf` on a variable, and a variable that was never assigned (a
+ * `beforeAll` that threw), or was assigned a fixture INSIDE the repo, must
+ * not become `rm -rf ''` or `rm -rf packages/`. The `dev-tools` copy of this
+ * helper carried that guard as a lexical `startsWith`; the guard here asks
+ * the filesystem, so a symlinked tmpdir (macOS) still passes.
+ *
+ * `force: true` tolerates a directory already gone; the retries are Node's
+ * own remedy for the transient `EBUSY` / `EPERM` a just-closed handle
+ * produces on Windows. Anything left after that is a real teardown failure
+ * and stays loud — a teardown that swallows it hides a leaking fixture.
+ *
+ * @param dir - The directory to remove
+ * @throws When `dir` is not strictly under the host tmpdir
+ */
+export function removeTempDir(dir) {
+    if (isUnderRoot(normalizedTmpdir(), dir) === 'outside') {
+        throw new Error(`removeTempDir: refusing to remove ${dir} — not inside the host tmpdir ${normalizedTmpdir()}`);
+    }
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}
+/**
+ * A factory that remembers every directory it minted, so one `afterEach`
+ * removes them all.
+ *
+ * @param prefix - `mkdtemp` prefix for every directory this tracker mints
+ * @returns `create` to mint one more, `cleanupAll` to remove every one so far
+ *
+ * @example
+ * ```typescript
+ * const scratch = tempDirTracker('my-suite-');
+ * afterEach(() => scratch.cleanupAll());
+ * it('…', () => { const dir = scratch.create(); … });
+ * ```
+ */
+export function tempDirTracker(prefix) {
+    const minted = [];
+    return {
+        create: () => {
+            const dir = createTempDir(prefix);
+            minted.push(dir);
+            return dir;
+        },
+        cleanupAll: () => {
+            for (const dir of minted)
+                removeTempDir(dir);
+            minted.length = 0;
+        },
+    };
+}
+/**
+ * How long a scratch-dir teardown may run before it gives up and warns.
+ *
+ * The value only has to be comfortably *under* the hook timeout it runs in —
+ * that is the whole design. Sizing a teardown budget to beat contention is
+ * unprovable (see {@link removeScratchDir}); sizing it below a known constant is
+ * arithmetic.
+ *
+ * ⚠️ **The known constant is the UNIT tier's**, which is the only tier that
+ * takes vitest's 10s default (`vitest.shared.ts` declines to override it there
+ * on purpose) and the tier where the flake was actually observed. The other two
+ * tiers set their own, far larger: integration gets `platformTestTimeout`
+ * (60s on Unix, 900s on Windows) and system gets 300s. A suite in those tiers
+ * inherits this 4s default and therefore gives up 15x–225x earlier than its hook
+ * would have allowed — for a heavy fixture tree that is a leaked directory and a
+ * warning bought for nothing, since an abandoned removal does not stop (see
+ * {@link removeScratchDir}). Such a suite should pass its own `budgetMs`, which
+ * both suite helpers forward.
+ */
+const SCRATCH_REMOVAL_BUDGET_MS = 4000;
+/**
+ * Delete a scratch directory as *best effort* — never failing the suite that
+ * created it, and never taking longer than its own budget to say so.
+ *
+ * ## Why this is not just `await rm(dir, { recursive: true, force: true })`
+ *
+ * A teardown hook that can redden a suite whose every assertion passed is a
+ * defect in the harness, not a flake. `packages/lab/test/instrument.test.ts`
+ * timed out here on two consecutive Windows runs with all 655 assertions
+ * green — only the cleanup lost.
+ *
+ * The measurement is what rules out the obvious fixes: that scratch dir holds
+ * 490 files / 378 KiB across 14 fixture git repos, and deletes in **59 ms**
+ * idle. Against vitest's 10,000 ms unit-hook budget that is 170x of headroom,
+ * and Windows blew through it anyway. No quantity of real work explains that,
+ * so the cause is scheduling — contention from a fully parallel `validate`,
+ * plus per-unlink antivirus on Windows — which is unbounded by nature. Hence:
+ *
+ * - **Raising `hookTimeout` cannot be argued.** You would be picking a number
+ *   to beat an unbounded quantity, when 10s of 170x headroom already lost. It
+ *   also punches a hole in the deliberate policy in `vitest.shared.ts` ("no
+ *   hookTimeout override here on purpose") for every unit hook, to fix one.
+ * - **`try`/`catch` around the `rm` cannot work.** A vitest hook timeout is a
+ *   race decided on the *timer* side; the hook's own catch never sees it. It
+ *   addresses a failure mode we did not observe and leaves the one we did.
+ * - **`maxRetries` alone makes it worse.** Retries target transient
+ *   `EPERM`/`EBUSY`, which fail *fast*; our failure was *slow*, and retry
+ *   backoff only adds to it. Kept below as a cheap inner win, not as the fix.
+ *
+ * So the deadline is taken away from vitest: the removal races a timer of our
+ * own, well inside the hook budget, and expiry is a warning rather than a
+ * failure. The hook therefore always resolves in time, which makes it
+ * *structurally* incapable of reddening a green suite on any machine at any
+ * load — rather than merely unlikely to.
+ *
+ * The cost, stated plainly: under pathological contention the directory
+ * survives in the OS temp dir, which the OS reclaims, and the warning names
+ * the path. It can never surface as an unhandled rejection, because the only
+ * rejection handler is installed before the race.
+ *
+ * ⚠️ **Abandoning the removal does not stop it, and does not free the worker.**
+ * A pending libuv `fs` request is an active handle, so the `rm` runs to
+ * completion regardless — measured at 2,407 ms on an 8,000-file tree after the
+ * race was decided at 5 ms — and the process cannot exit until it does.
+ * `timer.unref()` below unrefs the *timer*, not the removal. So what this buys
+ * is bounded: the **hook** always resolves in time, which is what stops a green
+ * suite going red. It does **not** shed the work, and under the contention it
+ * targets the abandoned removal competes for disk with whatever runs next in
+ * the same worker. That is the trade, and it is why the budget wants to be as
+ * large as the tier's hook allows rather than as small as possible.
+ *
+ * @param dir - Directory to remove. An empty string is a no-op, so a suite
+ *   whose `beforeAll` never ran can call this unconditionally.
+ * @param options - Deadline and warning sink
+ *
+ * @example
+ * ```typescript
+ * afterAll(async () => {
+ *   await removeScratchDir(scratch);
+ * });
+ * ```
+ */
+export async function removeScratchDir(dir, options = {}) {
+    if (dir === '')
+        return;
+    const budgetMs = options.budgetMs ?? SCRATCH_REMOVAL_BUDGET_MS;
+    const onWarn = options.onWarn ??
+        ((message) => {
+            console.warn(message);
+        });
+    // Latches on the first outcome so a removal that finishes (or fails) after
+    // the budget expired cannot log a second time into an already-finished suite.
+    let settled = false;
+    const giveUp = (reason) => {
+        if (settled)
+            return;
+        settled = true;
+        onWarn(`scratch dir left behind at ${dir}: ${reason}`);
+    };
+    const remove = options.remove ??
+        ((target) => fs.rm(target, { recursive: true, force: true, maxRetries: 2, retryDelay: 50 }));
+    const removal = remove(dir)
+        .then(() => {
+        settled = true;
+    })
+        .catch((error) => {
+        giveUp(error instanceof Error ? error.message : String(error));
+    });
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            giveUp(`removal did not finish within ${budgetMs}ms`);
+            resolve();
+        }, budgetMs);
+        // Never hold the process open for a teardown nobody is waiting on.
+        timer.unref();
+    });
+    await Promise.race([removal, deadline]);
+    clearTimeout(timer);
+}
+/**
+ * Get isolated test output directory for current test run
+ *
+ * Creates a unique directory under `packages/{packageName}/.test-output/{testType}/{runId}`
+ * where runId is `{timestamp}-{randomId}` to ensure isolation across parallel test runs.
+ *
+ * @param packageName - Name of package (e.g., 'rag-lancedb')
+ * @param testType - Type of test ('unit', 'integration', 'system')
+ * @param subdirs - Optional subdirectories to create within the test output directory
+ * @returns Absolute path to the created directory
+ *
+ * @example
+ * ```typescript
+ * // Create isolated database directory for system tests
+ * const dbPath = getTestOutputDir('rag-lancedb', 'system', 'databases', 'test-db');
+ * // Result: packages/rag-lancedb/.test-output/system/20260105-143022-abc123/databases/test-db
+ *
+ * // Create temporary file directory for integration tests
+ * const tempDir = getTestOutputDir('agent-skills', 'integration', 'temp-files');
+ * // Result: packages/agent-skills/.test-output/integration/20260105-143022-def456/temp-files
+ * ```
+ */
+export function getTestOutputDir(packageName, testType, ...subdirs) {
+    // Generate unique run ID: timestamp + random hex
+    const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').slice(0, 19);
+    const randomId = randomBytes(4).toString('hex');
+    const runId = `${timestamp}-${randomId}`;
+    // Find project root (assuming we're always in packages/*/test/*)
+    const projectRoot = safePath.resolve(process.cwd());
+    // Build path: packages/{packageName}/.test-output/{testType}/{runId}/{...subdirs}
+    const testOutputDir = safePath.join(projectRoot, 'packages', packageName, '.test-output', testType, runId, ...subdirs);
+    // Create directory structure and return normalized path
+    return mkdirSyncReal(testOutputDir, { recursive: true });
+}
+/**
+ * Get the base test output directory for a package
+ * Useful for cleanup operations that need to remove all test output
+ *
+ * @param packageName - Name of package (e.g., 'rag-lancedb')
+ * @returns Absolute path to packages/{packageName}/.test-output
+ *
+ * @example
+ * ```typescript
+ * const baseDir = getTestOutputBase('rag-lancedb');
+ * // Result: packages/rag-lancedb/.test-output
+ * ```
+ */
+export function getTestOutputBase(packageName) {
+    const projectRoot = safePath.resolve(process.cwd());
+    return safePath.join(projectRoot, 'packages', packageName, '.test-output');
+}
+/**
+ * Per-suite temp directory pattern (async version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @param teardown - Forwarded to {@link removeScratchDir}. Raise `budgetMs` for a
+ *   suite whose fixture tree is heavy or whose tier allows a longer hook than the
+ *   unit tier this default is sized against — see {@link SCRATCH_REMOVAL_BUDGET_MS}.
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupAsyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', async () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export function setupAsyncTempDirSuite(prefix, teardown = {}) {
+    let suiteDir = '';
+    let tempDir = '';
+    let testCounter = 0;
+    return {
+        beforeAll: async () => {
+            suiteDir = await fs.mkdtemp(safePath.join(normalizedTmpdir(), `${prefix}-suite-`));
+        },
+        afterAll: async () => {
+            await removeScratchDir(suiteDir, teardown);
+        },
+        beforeEach: async () => {
+            testCounter++;
+            tempDir = safePath.join(suiteDir, `test-${testCounter}`);
+            await fs.mkdir(tempDir, { recursive: true });
+        },
+        afterEach: async () => {
+            // Per-test cleanup handled by suite cleanup
+        },
+        getTempDir: () => tempDir,
+    };
+}
+/**
+ * Per-suite temp directory pattern (sync version)
+ * Creates a single temp directory for the entire test suite,
+ * with subdirectories for each test. This is 3-5x faster on Windows
+ * than creating a new mkdtemp for each test.
+ *
+ * @param prefix - Prefix for the suite temp directory name
+ * @param teardown - Forwarded to {@link removeScratchDir}. Raise `budgetMs` for a
+ *   suite whose fixture tree is heavy or whose tier allows a longer hook than the
+ *   unit tier this default is sized against — see {@link SCRATCH_REMOVAL_BUDGET_MS}.
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @example
+ * ```typescript
+ * const suite = setupSyncTempDirSuite('my-test');
+ *
+ * describe('my tests', () => {
+ *   beforeAll(suite.beforeAll);
+ *   afterAll(suite.afterAll);
+ *   beforeEach(suite.beforeEach);
+ *
+ *   it('test 1', () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export function setupSyncTempDirSuite(prefix, teardown = {}) {
+    let suiteDir = '';
+    let tempDir = '';
+    let testCounter = 0;
+    return {
+        beforeAll: () => {
+            suiteDir = mkdtempSync(safePath.join(normalizedTmpdir(), `${prefix}-suite-`));
+        },
+        afterAll: async () => {
+            await removeScratchDir(suiteDir, teardown);
+        },
+        beforeEach: () => {
+            testCounter++;
+            tempDir = safePath.join(suiteDir, `test-${testCounter}`);
+            mkdirSyncReal(tempDir);
+        },
+        afterEach: () => {
+            // Per-test cleanup handled by suite cleanup
+        },
+        getTempDir: () => tempDir,
+    };
+}
+//# sourceMappingURL=temp-dir.js.map

package/dist/testing/temp-dir.js.map

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

package/dist/testing.d.ts

@@ -1,8 +1,99 @@
 /**
- * @vibe-agent-toolkit/utils/testing
+ * Fixture primitives shared by suites in more than one package.
  *
- * Isolated temp-directory helpers for test suites. Node-only. Intended for
- * a consumer's test code — not for their shipped runtime.
+ * Deliberately framework-free: nothing here imports `vitest`, so this module
+ * stays a plain function library rather than something that registers hooks as a
+ * side effect of being imported. Each suite owns its own `beforeEach`/
+ * `afterEach` and calls these from inside them — two lines, which is below
+ * anything worth sharing, while the part that is genuinely identical (mkdtemp,
+ * write the literal, remove the tree) lives here once.
+ *
+ * It earned a home in `utils` the ordinary way: two packages needed it, not one
+ * package speculating that a second might.
+ *
+ * ⛔ **Do not import `vitest` here to share the hook wrapper itself.**
+ * `subpath-purity.test.ts` pins this entry at an EMPTY third-party set, and that
+ * pin is load-bearing: `./testing` is a published subpath, so a test framework
+ * reached from it becomes a runtime requirement for every adopter who imports
+ * it. {@link replantableCorpus} exists precisely so the per-test wrapper each
+ * suite still writes is three lines rather than twelve.
  */
+import type { UnreadablePolicy } from './listing-refusal.js';
 export * from './test-helpers.js';
+export { __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
+export * from './testing/executables.js';
+export * from './testing/hostile-tree.js';
+export * from './testing/platform-gates.js';
+export * from './testing/temp-dir.js';
+/** A planted fixture tree and the means to remove it. */
+export interface TempCorpus {
+    /** Absolute path to the tree's root. */
+    root: string;
+    /** Remove the tree. Safe to call when it is already gone. */
+    cleanup: () => void;
+}
+/**
+ * Write a literal corpus into a fresh temp directory.
+ *
+ * 🪤 Fixture files must NOT be byte-identical to each other when the suite is
+ * about content-addressed behaviour: VAT's blobs are keyed on their bytes plus
+ * the parser kind, so two files with the same content collapse into ONE blob and
+ * assertions then describe whichever path sorted first. Give each fixture a
+ * distinguishing marker line.
+ *
+ * ⚠️ The root is minted per call, so a suite that plants per test must call this
+ * per test — a root captured once and reused across tests survives its own
+ * `cleanup`.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @param corpus - Fixture name to file content; written verbatim as UTF-8.
+ *   Names may include forward-slash subpaths only if their parents already exist
+ * @returns The tree's root and its teardown
+ */
+export declare function createTempCorpus(prefix: string, corpus: Readonly<Record<string, string>>): TempCorpus;
+/** A corpus that can be planted and cleared repeatedly — one tree per test. */
+export interface ReplantableCorpus {
+    /** Plant a fresh tree. Drive from the suite's `beforeEach`. */
+    plant: () => void;
+    /** Remove the current tree, if any. Drive from the suite's `afterEach`. */
+    clear: () => void;
+    /** The root minted by the most recent {@link plant}. */
+    root: () => string;
+}
+/**
+ * Hold a per-test corpus root, so a suite's hook wrapper is three lines.
+ *
+ * ⚠️ **The root comes back through a GETTER, never as a value.** A per-test
+ * fixture is reminted for every test, so a root captured at registration time is
+ * `undefined` in the first test and stale in every one after it. That mistake is
+ * the reason this holder exists rather than each suite keeping its own `let`.
+ *
+ * ⭐ Framework-free on purpose: it takes no hooks and registers none, so the
+ * suite still owns its own `beforeEach`/`afterEach` and this module keeps the
+ * empty third-party set its purity pin asserts. See the module docstring.
+ *
+ * 🪤 `root()` before the first `plant()` THROWS by name. The shape it replaced
+ * read an uninitialised `let` and raised `Cannot read properties of undefined`
+ * from inside the fixture, which names neither the suite nor the missing hook.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @param corpus - Fixture name to file content, as {@link createTempCorpus} takes it
+ * @returns Plant/clear/root, to be driven from the caller's own hooks
+ */
+export declare function replantableCorpus(prefix: string, corpus: Readonly<Record<string, string>>): ReplantableCorpus;
+/**
+ * The `unreadable` policy a FIXTURE crawl states: refuse, against the fixture
+ * root, with a remedy that names the fixture rather than an adopter knob.
+ *
+ * A suite that is not ABOUT refusals still has to say what one would mean —
+ * the policy is required, with no default, and test files are not typechecked
+ * — and the honest answer for a planted tree is that a directory it cannot
+ * list is a broken fixture, not a case to degrade around. A suite that IS
+ * about refusals spells its own policy inline, because the policy is the
+ * subject.
+ *
+ * @param root - The fixture root the refused directory is expressed against
+ * @returns A `refuse` policy for `crawlDirectory` and the git listings
+ */
+export declare function refuseUnreadableFixture(root: string): UnreadablePolicy;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAG3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AAEtC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,UAAU,CAMZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,iBAAiB,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAEtE"}

package/dist/testing.js

@@ -1,8 +1,124 @@
 /**
- * @vibe-agent-toolkit/utils/testing
+ * Fixture primitives shared by suites in more than one package.
  *
- * Isolated temp-directory helpers for test suites. Node-only. Intended for
- * a consumer's test code — not for their shipped runtime.
+ * Deliberately framework-free: nothing here imports `vitest`, so this module
+ * stays a plain function library rather than something that registers hooks as a
+ * side effect of being imported. Each suite owns its own `beforeEach`/
+ * `afterEach` and calls these from inside them — two lines, which is below
+ * anything worth sharing, while the part that is genuinely identical (mkdtemp,
+ * write the literal, remove the tree) lives here once.
+ *
+ * It earned a home in `utils` the ordinary way: two packages needed it, not one
+ * package speculating that a second might.
+ *
+ * ⛔ **Do not import `vitest` here to share the hook wrapper itself.**
+ * `subpath-purity.test.ts` pins this entry at an EMPTY third-party set, and that
+ * pin is load-bearing: `./testing` is a published subpath, so a test framework
+ * reached from it becomes a runtime requirement for every adopter who imports
+ * it. {@link replantableCorpus} exists precisely so the per-test wrapper each
+ * suite still writes is three lines rather than twelve.
  */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { normalizedTmpdir, safePath } from './path-utils.js';
+// The rest of the testing surface. ⚠️ This re-export is the ENTIRETY of what
+// `./testing` used to be, and dropping it silently removed `detachGitEnv`,
+// `setupSyncTempDirSuite` and every sibling from a published subpath. A module
+// that is both a definition site and a barrel loses the barrel first.
 export * from './test-helpers.js';
+// The crawl-timing recorder's test seams: read the snapshot, point it at a
+// directory, flush a dump. Test scaffolding, so they live on this subpath and
+// not on the runtime barrel that publishes the recorder itself.
+export { __readCrawlTimingSnapshot, __setCrawlTimingForTest, __writeCrawlTimingDumpForTest, } from './crawl-timing.js';
+// The three fixture modules the sinks' suites share: the ONE temp-dir family,
+// the host gates, and the hostile tree every sink is tested against.
+export * from './testing/executables.js';
+export * from './testing/hostile-tree.js';
+export * from './testing/platform-gates.js';
+export * from './testing/temp-dir.js';
+/**
+ * Write a literal corpus into a fresh temp directory.
+ *
+ * 🪤 Fixture files must NOT be byte-identical to each other when the suite is
+ * about content-addressed behaviour: VAT's blobs are keyed on their bytes plus
+ * the parser kind, so two files with the same content collapse into ONE blob and
+ * assertions then describe whichever path sorted first. Give each fixture a
+ * distinguishing marker line.
+ *
+ * ⚠️ The root is minted per call, so a suite that plants per test must call this
+ * per test — a root captured once and reused across tests survives its own
+ * `cleanup`.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @param corpus - Fixture name to file content; written verbatim as UTF-8.
+ *   Names may include forward-slash subpaths only if their parents already exist
+ * @returns The tree's root and its teardown
+ */
+export function createTempCorpus(prefix, corpus) {
+    const root = mkdtempSync(safePath.join(normalizedTmpdir(), prefix));
+    for (const [name, content] of Object.entries(corpus)) {
+        writeFileSync(safePath.join(root, name), content, 'utf8');
+    }
+    return { root, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+/**
+ * Hold a per-test corpus root, so a suite's hook wrapper is three lines.
+ *
+ * ⚠️ **The root comes back through a GETTER, never as a value.** A per-test
+ * fixture is reminted for every test, so a root captured at registration time is
+ * `undefined` in the first test and stale in every one after it. That mistake is
+ * the reason this holder exists rather than each suite keeping its own `let`.
+ *
+ * ⭐ Framework-free on purpose: it takes no hooks and registers none, so the
+ * suite still owns its own `beforeEach`/`afterEach` and this module keeps the
+ * empty third-party set its purity pin asserts. See the module docstring.
+ *
+ * 🪤 `root()` before the first `plant()` THROWS by name. The shape it replaced
+ * read an uninitialised `let` and raised `Cannot read properties of undefined`
+ * from inside the fixture, which names neither the suite nor the missing hook.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @param corpus - Fixture name to file content, as {@link createTempCorpus} takes it
+ * @returns Plant/clear/root, to be driven from the caller's own hooks
+ */
+export function replantableCorpus(prefix, corpus) {
+    let planted;
+    return {
+        plant: () => {
+            // 🪤 Removes any tree still standing FIRST. Nested `describe` blocks each
+            // get their own `beforeEach` and vitest runs outer-then-inner before a
+            // single `afterEach`, so a double plant is ordinary rather than exotic.
+            // Overwriting the handle without this would leak the first tree for the
+            // process's lifetime, silently and only on the suites that nest.
+            planted?.cleanup();
+            planted = createTempCorpus(prefix, corpus);
+        },
+        clear: () => {
+            planted?.cleanup();
+            planted = undefined;
+        },
+        root: () => {
+            if (planted === undefined) {
+                throw new Error(`replantableCorpus('${prefix}'): root() before plant() — the suite is missing its beforeEach`);
+            }
+            return planted.root;
+        },
+    };
+}
+/**
+ * The `unreadable` policy a FIXTURE crawl states: refuse, against the fixture
+ * root, with a remedy that names the fixture rather than an adopter knob.
+ *
+ * A suite that is not ABOUT refusals still has to say what one would mean —
+ * the policy is required, with no default, and test files are not typechecked
+ * — and the honest answer for a planted tree is that a directory it cannot
+ * list is a broken fixture, not a case to degrade around. A suite that IS
+ * about refusals spells its own policy inline, because the policy is the
+ * subject.
+ *
+ * @param root - The fixture root the refused directory is expressed against
+ * @returns A `refuse` policy for `crawlDirectory` and the git listings
+ */
+export function refuseUnreadableFixture(root) {
+    return { refuse: { root, remedy: 'A test fixture must be listable in full; fix the fixture, not the walk.' } };
+}
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,sEAAsE;AACtE,cAAc,mBAAmB,CAAC;AAClC,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,qEAAqE;AACrE,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AAUtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAwC;IAExC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAAwC;IAExC,IAAI,OAA+B,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,0EAA0E;YAC1E,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,iEAAiE,CAC9F,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,yEAAyE,EAAE,EAAE,CAAC;AACjH,CAAC"}