@ghostry/fabricator 0.0.2 → 0.0.3

package/dist/types/index.d.ts

@@ -1,46 +1,31 @@
 import type { Limits } from "./Enumeration/Types";
 import type { Instance, Stack } from "./Instance/Types";
-import type { Algorithm, Attribution, Seed } from "./Random/Types";
+import type { Algorithm, Salt } from "./Random/Types";
 import { registry } from "./Schema/Registry";
 import type { PlainObject } from "./Utility/Types";
 export declare function initialize<const $Registry extends PlainObject = typeof registry>(config?: Partial<{
     /** The registry of type definers to use — `registry` itself. */
     types: $Registry;
     /**
-     * Optional mixer composed into every stream beside `clock`. Accepts a
-     * single string, or several — several lets a seed be composed out of
-     * independent, meaningful parts (a user id, a scenario label) without
-     * hand-joining them first. If omitted, the seed is empty (unless
-     * `FABRICATOR_SEED` / `SEED` / `RANDOM_SEED` supplies one): wall-clock
-     * `clock` is the default entropy, so an unconfigured instance varies by run
-     * and replays from `context.clock` alone. Pass a seed when two instances
-     * should share a clock but draw different universes, or when `clock:
-     * "seeded"` should make the seed itself the reproducibility unit.
+     * Optional differentiator composed into every stream beside `clock` — it
+     * distinguishes runs, it does not generate them. Accepts a single string,
+     * or several — several lets a salt be composed out of independent,
+     * meaningful parts (a user id, a scenario label) without hand-joining them
+     * first. If omitted, the salt is empty (unless `FABRICATOR_SALT` supplies
+     * one): wall-clock `clock` is the default entropy, so an unconfigured
+     * instance varies by run and replays from `context.clock` alone. Pass a
+     * salt when two instances should share a clock but draw different
+     * universes, or when `clock: "derived"` should make the salt itself the
+     * reproducibility unit.
      */
-    seed?: Seed;
+    salt?: Salt;
     /**
      * Bring your own PRNG: a factory that, given a seed, returns a source of
      * randomness — a `() => number` in `[0, 1)`, a drop-in for `Math.random`.
-     * Defaults to the built-in `sfc32` generator.
+     * The seed is a whole encoded trace, of which `salt` is one slot, not the
+     * `salt` itself. Defaults to the built-in `sfc32` generator.
      */
     algorithm?: Algorithm;
-    /**
-     * How this instance attributes a construction's randomness to the file it
-     * was written in:
-     *
-     * - `{ kind: "rooted", root }` expresses every file relative to `root` (an
-     *   absolute path or a `file://` URL), so the same seed reproduces the same
-     *   data on a checkout at a different absolute path.
-     * - `{ kind: "call site" }`, the default, is `"rooted"` at the directory of
-     *   whichever file called `initialize()`.
-     * - `{ kind: "none" }` attributes nothing: every construction of a given kind
-     *   anywhere in the instance shares one stream, keyed by kind alone.
-     *
-     * See
-     * [Reproducibility](https://docs.ghostry.dev/fabricator/guides/reproducibility)
-     * for the trade-offs between the three.
-     */
-    attribution?: Attribution;
     /**
      * Instance-wide numeric ceilings. `combinatorial` bounds how many instances
      * `combinatorial(...)` may enumerate — the check is eager, it throws at
@@ -55,14 +40,14 @@ export declare function initialize<const $Registry extends PlainObject = typeof
      * every leaf's trace, the default entropy for the instance. Defaults to the
      * wall-clock instant of this `initialize()` call, so an unconfigured run
      * has realistic dates and varies by process, and replays from
-     * `context.clock` (with the same empty or supplied `seed`). Pass a fixed
-     * `Date` to freeze "now" (and the rest of the run, unless `seed` also
-     * differs). Pass `"seeded"` to derive "now" from the instance seed instead
+     * `context.clock` (with the same empty or supplied `salt`). Pass a fixed
+     * `Date` to freeze "now" (and the rest of the run, unless `salt` also
+     * differs). Pass `"derived"` to derive "now" from the instance salt instead
      * — an instant drawn across the whole representable `Date` span, so an
      * implausible date is the expected outcome of that policy, not a bug.
-     * `"seeded"` is what makes `seed` alone the reproducibility unit.
+     * `"derived"` is what makes `salt` alone the reproducibility unit.
      */
-    clock?: Date | "seeded";
+    clock?: Date | "derived";
     /**
      * The ambient carrier backing `wrap` for this lineage — override only to
      * force a specific one.
@@ -79,14 +64,14 @@ export declare function initialize<const $Registry extends PlainObject = typeof
 }>): Instance<$Registry>;
 export { Omitted } from "./Types";
 /**
- * Tags a `Seed` — for `new Fabricator(schema, { seed })`, or `fork`'s own
- * `Overlay.seed` — as composing onto whatever base is in effect, rather than
+ * Tags a `Salt` — for `new Fabricator(schema, { salt })`, or `fork`'s own
+ * `Overlay.salt` — as composing onto whatever base is in effect, rather than
  * replacing it outright.
  */
 export { layer } from "./Random";
 /**
  * `layer(...)`'s return type, so a caller building one programmatically can
- * name it — the same rationale as the existing `Seed`/`Attribution` exports.
+ * name it — the same rationale as the existing `Salt` export.
  */
 export type { Layered } from "./Random/Types";
 /**
@@ -95,25 +80,6 @@ export type { Layered } from "./Random/Types";
  * subclasses are distinguished by `.name`.
  */
 export { FabricatorError } from "./Error";
-/**
- * The adapter contract, exported because an adapter is a separate package
- * rather than something registered here: `Adapter`/`Recurse` are what one
- * declares, `drive` is what its conversion entry point calls, and
- * `Adaptation`/`AdaptationsOf` are how it reads what a Schema declared —
- * `[Adaptation]` at runtime, `AdaptationsOf` at the type level, keyed by its
- * own `key` in both cases.
- *
- * This package names no external schema library and depends on none: every
- * mapping, and every dependency it needs, belongs to the adapter.
- *
- * `Adapting` is the odd one out, facing whoever _writes_ an adaptation rather
- * than whoever implements an adapter: it is the parameter type of every kind's
- * `.adapt(adapter, produce)` producer, so a caller writing that producer as a
- * named function can name it — the same reason `Stream` is exported below.
- */
-export { drive } from "./Adapter/Core";
-export type { Adaptations, AdaptationsOf, Adapter, Adapting, Recurse, } from "./Adapter/Types";
-export { Adaptation } from "./Types";
 /**
  * The default registry of type definers, exported so it can be extended via
  * `registry.extend(({ T }) => ({ ... }))` before being passed to `initialize({
@@ -142,17 +108,23 @@ export type { Stream } from "./Random/Types";
  */
 export type { ProduceContext } from "./Random/Types";
 /**
- * The shape `initialize({ seed })` and `new Fabricator(schema, { seed })` both
- * accept — a single string, or several — so a caller building one
- * programmatically (rather than as an inline literal) can name the type.
+ * What every kind's `.adapt(adapter, produce)` producer is called with — `{
+ * schema, meta }` — the same rationale as `Stream`/`ProduceContext` above: a
+ * caller writing the producer as a named function can name its parameter.
+ * `meta` is the kind's own config, reachable here without importing the `Meta`
+ * well-known symbol from `@ghostry/fabricator/internal` — that symbol stays off
+ * the path an ordinary caller writing an `.adapt()` call has to walk. The rest
+ * of the adapter contract (`walk`, `Adapter`, `Adaptation`, `Adaptations`,
+ * `AdaptationsOf`, `Recurse`) is exported from `@ghostry/fabricator/adapting`
+ * instead — surface for implementing an adapter, not for calling `.adapt()`.
  */
-export type { Seed } from "./Random/Types";
+export type { Adapting } from "./Adapter/Types";
 /**
- * The shape `initialize({ attribution })` accepts, so a caller building one
- * programmatically — a rooted policy derived from an env var, say — can name
- * the type.
+ * The shape `initialize({ salt })` and `new Fabricator(schema, { salt })` both
+ * accept — a single string, or several — so a caller building one
+ * programmatically (rather than as an inline literal) can name the type.
  */
-export type { Attribution } from "./Random/Types";
+export type { Salt } from "./Random/Types";
 /**
  * Reads the value type a built Fabricator produces straight off its `fabricate`
  * signature — `Fabrication<typeof Product>` instead of `ReturnType<typeof
@@ -170,19 +142,12 @@ export type { ValueOf } from "./Schema/Types";
  * onto one, the same reason `Stream` is exported above.
  */
 export type { Trace } from "./Random/Types";
-/**
- * How `file` and `ordinal` on a {@link Trace} were resolved — recorded so a
- * captured trace is self-describing, including `"counted"` (replayed for a node
- * taken from inside a `T.recursive` expansion; not a variant you choose when
- * building).
- */
-export type { RootKind } from "./Random/Types";
 /**
  * `fork`/`wrap`'s own config shapes, so a caller building an overlay
  * programmatically (rather than as an inline literal) can name them — the same
- * rationale as the existing `Seed`/`Attribution` exports. `Config` is what
- * `initialize`'s own parameter is a `Partial` of; `Overlay` is what
- * `fork`/`wrap` accept; `Context` is `instance.context`'s own type, so a caller
- * writing a helper that reads it can name the parameter.
+ * rationale as the existing `Salt` export. `Config` is what `initialize`'s own
+ * parameter is a `Partial` of; `Overlay` is what `fork`/`wrap` accept;
+ * `Context` is `instance.context`'s own type, so a caller writing a helper that
+ * reads it can name the parameter.
  */
 export type { Config, Context, Overlay, Stack } from "./Instance/Types";

package/dist/types/internal.d.ts

@@ -58,30 +58,12 @@ export type { Constructor } from "./Fabricator/Constructor";
 export { plan, resolve } from "./Enumeration/Plan";
 export type { Axis, Enumerable, Pin, Resolvable } from "./Enumeration/Types";
 /**
- * The randomness layer underneath `initialize({ seed, algorithm, attribution
- * })` and a Fabricator's `.trace` — needed by tests exercising stream
- * attribution and construction directly, beneath the level `initialize()`
- * itself exposes.
+ * The randomness layer underneath `initialize({ clock, salt, algorithm })` and
+ * a Fabricator's `.trace` — needed by tests exercising stream construction
+ * directly, beneath the level `initialize()` itself exposes.
  */
-export { defaultAlgorithm, encode, randomSeed, toRandomSource, toStream, toStreamFromTrace, } from "./Random";
-export type { Algorithm, ConstructionTrace, ConstructorOptions, ResolvedAttribution, RootKind, RootPins, Seed, Trace, } from "./Random/Types";
-/**
- * `Random/CallSite.ts`'s pure string helpers. Exported for this package's own
- * tests: the percent-encoded, `file://`-prefixed, and backslashed spellings
- * they exist to fold together cannot be produced by running the suite from an
- * ordinary POSIX checkout, so they have to be driven with synthetic frame
- * strings instead of real stack frames.
- */
-export { directoryOf, normalizeLocation, relativize } from "./Random/CallSite";
-/**
- * Resolves the file that triggered the current call. Exported here for a
- * library that wraps fabricator (e.g. `@ghostry/extern`'s testing scope) and
- * wants a construction attributed to _its own_ caller rather than to itself,
- * which is what the `skip` option is for. See `Random/CallSite.ts`'s doc
- * comment for the full contract, including why `skip` is a list of roots that
- * composes onto this library's own root rather than replacing it.
- */
-export { resolveCallerFile } from "./Random/CallSite";
+export { defaultAlgorithm, encode, randomSalt, toRandomSource, toStream, toStreamFromTrace, } from "./Random";
+export type { Algorithm, ConstructionTrace, ConstructorOptions, RootPins, Salt, Trace, } from "./Random/Types";
 /**
  * The synchronous ambient carrier. `#stack` (`package.json`) selects it only
  * where there is no `node:async_hooks` — in practice a browser bundle — so on

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@ghostry/fabricator",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "license": "MIT",
   "description": "Fabricate typed data from composable schemas.",
   "keywords": [
-    "factory"
+    "factory",
+    "reproducible",
+    "fixtures",
+    "testing",
+    "mock",
+    "schema",
+    "typescript"
   ],
   "author": {
     "name": "Patrick Rebsch"
@@ -14,9 +20,13 @@
     "url": "git+https://github.com/ghostry-dev/fabricator",
     "directory": "pkg/fabricator"
   },
-  "homepage": "https://github.com/ghostry-dev/fabricator",
+  "homepage": "https://docs.ghostry.dev/fabricator/",
   "bugs": "https://github.com/ghostry-dev/fabricator/issues",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "types": "./dist/types/index.d.ts",
   "module": "./dist/esm/index.js",
   "imports": {
@@ -38,6 +48,16 @@
       "types": "./dist/types/internal.d.ts",
       "import": "./dist/esm/internal.js",
       "default": "./dist/esm/internal.js"
+    },
+    "./adapting": {
+      "types": "./dist/types/adapting.d.ts",
+      "import": "./dist/esm/adapting.js",
+      "default": "./dist/esm/adapting.js"
+    },
+    "./harnessing": {
+      "types": "./dist/types/harnessing.d.ts",
+      "import": "./dist/esm/harnessing.js",
+      "default": "./dist/esm/harnessing.js"
     }
   },
   "publishConfig": {

package/dist/esm/Random/CallSite.js

@@ -1,70 +0,0 @@
-const OWN_ROOT = normalizeLocation(new URL("..", import.meta.url).href);
-function stripPosition(text) {
-    return text.replace(/:\d+:\d+/g, "");
-}
-function extractLocation(frameLine) {
-    const trimmed = frameLine.trim().replace(/^at\s+/, "");
-    const parenthesized = trimmed.match(/\(([^()]*)\)$/);
-    return parenthesized ? parenthesized[1] : trimmed;
-}
-function decode(text) {
-    try {
-        return decodeURIComponent(text);
-    } catch  {
-        return text;
-    }
-}
-function normalizeLocation(location) {
-    const isUrl = location.startsWith("file://");
-    const path = isUrl ? decode(location.slice(7)) : location;
-    return path.replace(/\\/g, "/").replace(/^\/?([A-Za-z]):\//, (_, letter)=>`/${letter.toUpperCase()}:/`);
-}
-function directoryOf(location) {
-    const cut = location.lastIndexOf("/");
-    return -1 === cut ? location : location.slice(0, cut + 1);
-}
-function relativize(root, file) {
-    if (!file.startsWith("/")) return file;
-    const from = root.split("/").filter(Boolean);
-    const to = file.split("/").filter(Boolean);
-    let shared = 0;
-    while(shared < from.length && shared < to.length && from[shared] === to[shared])shared++;
-    const traversals = Array(from.length - shared).fill("..");
-    return [
-        ...traversals,
-        ...to.slice(shared)
-    ].join("/");
-}
-function isInternalFrame(location, otherInternals = []) {
-    if (location.startsWith(OWN_ROOT)) return true;
-    return otherInternals.some((skip)=>location.startsWith(skip));
-}
-function firstExternalFrame(stack, otherInternals = []) {
-    var _ref, _locations_find;
-    const locations = stack.split("\n").filter((line)=>line.trim().startsWith("at ")).map(extractLocation).map(normalizeLocation);
-    return null != (_ref = null != (_locations_find = locations.find((location)=>!isInternalFrame(location, otherInternals))) ? _locations_find : locations[locations.length - 1]) ? _ref : stack;
-}
-function resolveCallerFile(options) {
-    var _options_skip;
-    const skip = null == options ? void 0 : null == (_options_skip = options.skip) ? void 0 : _options_skip.map(normalizeLocation);
-    const stack = captureRawStack();
-    const location = stripPosition(stack.walkable ? firstExternalFrame(stack.text, skip) : stack.text);
-    return (null == options ? void 0 : options.root) === void 0 ? location : relativize(normalizeLocation(options.root), location);
-}
-function captureRawStack() {
-    var _captured_stack;
-    if ("function" != typeof Error.captureStackTrace) {
-        var _stack;
-        return {
-            text: null != (_stack = new Error().stack) ? _stack : "",
-            walkable: false
-        };
-    }
-    const captured = {};
-    Error.captureStackTrace(captured);
-    return {
-        text: null != (_captured_stack = captured.stack) ? _captured_stack : "",
-        walkable: true
-    };
-}
-export { directoryOf, normalizeLocation, relativize, resolveCallerFile };

package/dist/types/Random/CallSite.d.ts

@@ -1,78 +0,0 @@
-/**
- * One canonical form for a location, whatever produced it: Node ESM emits
- * `file:///…` URLs, Bun emits bare absolute paths, and this module's own
- * `import.meta.url` is percent-encoded — three spellings of one file that must
- * compare equal, or `isInternalFrame`/`relativize` silently stop matching. A
- * bare path is trusted as-is and never decoded, since it may contain a literal
- * `%20`; only the `file://` form's escaping is guaranteed well-formed. Forward
- * slashes and an uppercased leading `/X:/` drive fold Windows' `C:\a\b` and
- * `file:///c:/a/b` together — the drive is the one component two sources
- * disagree on, so it's the only thing case-folded: doing more would break
- * case-sensitive filesystems and change what ends up hashed.
- */
-export declare function normalizeLocation(location: string): string;
-/**
- * The directory a location sits in, trailing separator included — without it, a
- * root of `/a/b/` would match the unrelated sibling `/a/bcd/x.ts`, since
- * `startsWith`/prefix-stripping only sees character runs, not path segments.
- */
-export declare function directoryOf(location: string): string;
-/**
- * `file` expressed relative to `root`, ascending with `..` where `file` sits
- * outside `root` rather than falling back to `file` unchanged. An ascending
- * path stays identical across machines whose checkouts hold both locations at
- * the same relative position, the common case for anything under the same
- * repository — passing an escaping file through as absolute would defeat the
- * default `"call site"` policy for every schema helper that isn't a sibling of
- * wherever `initialize()` was called. A location that isn't an absolute path
- * (`native`, `<anonymous>`, or a value that has already been relativized)
- * doesn't start with `/` and is returned unchanged — applying this twice is a
- * no-op, which lets `T.recursive` thread an already-relativized file back
- * through here uniformly.
- */
-export declare function relativize(root: string, file: string): string;
-/**
- * Resolve the file that (transitively) triggered the current call, so
- * construction can be attributed to the source file the user wrote it in.
- *
- * Primary path: `Error.captureStackTrace` (V8, and Bun for Node compatibility)
- * captures the full stack, then `firstExternalFrame` skips this library's own
- * frames by path — no need to hardcode how many frames to exclude, so it stays
- * correct as internal call depth changes.
- *
- * Fallback: engines without `captureStackTrace` get the whole raw stack,
- * position-stripped, hashed as-is rather than guessing which frame to isolate.
- * Lower fidelity (sensitive to edits anywhere in the visible call chain, not
- * just the immediate caller), but rarely exercised — Bun, Node, and Chrome all
- * support the primary path. Left unnormalized: a whole multi-line stack has no
- * single location for `normalizeLocation`'s separator/drive rewriting to apply
- * to, so this path never relativizes — it always falls through `relativize`'s
- * non-absolute passthrough instead.
- *
- * Both options exist for a library that wraps fabricator and wants to attribute
- * a construction to _its own_ caller rather than to itself —
- * `@ghostry/extern`'s testing scope is the motivating case: it opens a `wrap`
- * per test and wants the resolved site to be the test file, not `extern`'s own
- * module. This module's own callers (`resolveAttribution`'s `"call site"`
- * branch, `resolveRootFile`) pass neither.
- *
- * `skip`, when given, is a list of _additional_ roots to exclude — layered onto
- * `OWN_ROOT`, never replacing it. With a wrapper between fabricator and the
- * real caller, the stack reads fabricator → wrapper → caller: omitting
- * `OWN_ROOT` from the skip set would make this resolve to fabricator's own file
- * instead of stopping at the wrapper.
- *
- * Always a list, never a bare root: a _chain_ of wrappers needs every link
- * named, and any link left out is where resolution stops. An integration
- * layered on another integration reads fabricator → inner → outer → caller —
- * `@ghostry/extern`'s fabricator extension sits between fabricator and extern
- * exactly this way.
- *
- * `root`, when given, relativizes the result exactly as a `{ kind: "rooted" }`
- * attribution policy does ({@link relativize}) — so a caller needs no separate
- * import to get a checkout-relative path.
- */
-export declare function resolveCallerFile(options?: {
-    readonly skip?: readonly string[];
-    readonly root?: string;
-}): string;