@ghostry/fabricator 0.0.1 → 0.0.2

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

@@ -1,59 +1,78 @@
 /**
- * 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 `isOwnFrame`/`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.
+ * 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.
+ * 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.
+ * `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.
+ * 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.
+ * 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
+ * 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(): string;
+export declare function resolveCallerFile(options?: {
+    readonly skip?: readonly string[];
+    readonly root?: string;
+}): string;

package/dist/types/Random/Generator/sfc32.d.ts

@@ -1,9 +1,9 @@
 import type { NumberGenerator } from "../Types";
 /**
- * sfc32 ("Small Fast Counter"): a 128-bit-state PRNG that is fast, compact,
- * and statistically strong (passes both PractRand and TestU01 BigCrush).
- * Each call advances the state and returns the top 32 bits scaled into
- * `[0, 1)`. Non-cryptographic: never use this for secrets or tokens.
+ * sfc32 ("Small Fast Counter"): a 128-bit-state PRNG that is fast, compact, and
+ * statistically strong (passes both PractRand and TestU01 BigCrush). Each call
+ * advances the state and returns the top 32 bits scaled into `[0, 1)`.
+ * Non-cryptographic: never use this for secrets or tokens.
  *
  * @see https://stackoverflow.com/a/47593316
  */