@jterrazz/test 15.3.0 → 16.1.0

package/dist/fixtures.js

@@ -0,0 +1,110 @@
+import { basename, dirname, resolve } from "node:path";
+//#region src/model/chain/ground.ts
+/**
+* The GROUND a row of specs stands on — the naming law of a spec tree.
+*
+* In a row of specs, a MEMBER is a spec: `<aspect>.test.ts`, `<case>.spec.yaml`,
+* `<name>.specification.ts`, and the facet/domain folders that hold them.
+* Everything else in that row is what the members STAND ON — inert material the
+* framework resolves BY PATH, never imported, never executed — and it carries a
+* LEADING UNDERSCORE. A spec's own folder never does.
+*
+* Four names, and only four: `_fixtures/` (file state), `_expected/` (goldens),
+* `_requests/` (inputs), `_seeds/` (database state). `contracts/` is NOT ground —
+* a contract is TypeScript a spec imports, behaviour composed with the spec's own,
+* so it stays a member. `docker/` is not ground either: it sits at the PROJECT
+* root beside `package.json`, outside any row of specs.
+*
+* This module is the single home of those names. Every resolver, matcher, lint
+* rule and checker pass reads them from here, so the runtime and the static
+* channels cannot disagree about where a spec's ground lives.
+*/
+/** Goldens: every expected fixture, flat, extension included. */
+const GROUND_EXPECTED = "_expected";
+/** File state copied into a working directory by `.fixture()`. */
+const GROUND_FIXTURES = "_fixtures";
+/** Inputs: complete `.http` request documents. */
+const GROUND_REQUESTS = "_requests";
+/** Database state: `.sql` fragments loaded by `.seed()`. */
+const GROUND_SEEDS = "_seeds";
+/** The four ground directory names, in the order they read. */
+const GROUND_DIRS = [
+	GROUND_EXPECTED,
+	GROUND_FIXTURES,
+	GROUND_REQUESTS,
+	GROUND_SEEDS
+];
+//#endregion
+//#region src/model/chain/fixtures.ts
+/**
+* Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
+*
+* A fixture path is one of two shapes:
+*
+*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/_fixtures/<rest>`,
+*    where `<specs-root>` is the nearest ancestor directory named `specs`.
+*  - `<path>` (no marker) — feature-local, at `<test-dir>/_fixtures/<path>`.
+*
+* The leading underscore is the ground rule of a spec tree ({@link GROUND_FIXTURES}).
+* Any other `$`-prefixed marker is a usage error (listed against the known
+* markers). Copy semantics mirror rsync's trailing-slash rule (see
+* {@link copyPlan}).
+*/
+/**
+* Markers understood in a `.fixture()` path. Extend here + in
+* {@link resolveFixtureSource}. Exported so the lint layer (rule
+* `jterrazz/b2-known-fixture-marker`) validates literals against the same list.
+*/
+const KNOWN_FIXTURE_MARKERS = ["$FIXTURES"];
+/**
+* Walk up from `startDir` to the nearest ancestor directory named `specs`.
+* Throws with guidance if none is found up to the filesystem root — the
+* `$FIXTURES` marker is meaningless without a specs root.
+*/
+function discoverSpecsRoot(startDir) {
+	let dir = startDir;
+	for (;;) {
+		if (basename(dir) === "specs") return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/${GROUND_FIXTURES}, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local ${GROUND_FIXTURES}/ path (no $FIXTURES marker).`);
+}
+/**
+* Resolve the absolute source path of a fixture, applying marker resolution.
+* The trailing slash (spread semantics) is preserved by callers via
+* {@link copyPlan} — it is irrelevant to source resolution.
+*/
+function resolveFixtureSource(path, testDir) {
+	const clean = path.replace(/\/+$/u, "");
+	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
+		const rest = clean.slice(9).replace(/^\/+/u, "");
+		return resolve(discoverSpecsRoot(testDir), GROUND_FIXTURES, rest);
+	}
+	if (path.startsWith("$")) {
+		const marker = clean.split("/")[0];
+		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/${GROUND_FIXTURES}/).`);
+	}
+	return resolve(testDir, GROUND_FIXTURES, clean);
+}
+/**
+* Compute the source + destination for copying a fixture into the working
+* directory. Copy semantics follow rsync's trailing-slash rule:
+*
+*  - `dir/` (trailing slash) — the CONTENTS are spread into the cwd.
+*  - `dir`  (no slash, a directory) — the directory is copied as `<cwd>/<basename>`.
+*  - `file` — copied as `<cwd>/<basename>`.
+*
+* Chained `.fixture()` calls layer in order: a later fixture overwrites files
+* written by an earlier one.
+*/
+function copyPlan(path, testDir, workDir) {
+	const src = resolveFixtureSource(path, testDir);
+	return {
+		dest: /\/+$/u.test(path) ? workDir : resolve(workDir, basename(src)),
+		src
+	};
+}
+//#endregion
+export { GROUND_FIXTURES as a, GROUND_EXPECTED as i, resolveFixtureSource as n, GROUND_REQUESTS as o, GROUND_DIRS as r, GROUND_SEEDS as s, copyPlan as t };