@sibylline-labs/eris 0.0.0-stage → 0.3.1

package/testing/build-child.ts

@@ -0,0 +1,55 @@
+/**
+ * build-child.ts — `build()` in a child bun process, for a suite that needs a
+ * compiled binary.
+ *
+ * A compile in the test process is not repeatable across test files: on Linux
+ * (bun 1.3.13, linux-x64 runner and a linux container) a later file's
+ * `Bun.build` fails with `EBADF` / `Unexpected reading file` on a module an
+ * earlier file's compile read, while each file alone passes. One process per
+ * build shares no bundler state with the suite or with another build.
+ *
+ *   buildInChild({ module: join(root, "build.ts"), outfile, tag: "v0.0.1" })
+ *
+ * `module` is the file of a build, an absolute path to a module that exports
+ * `BUILD`, the `BuildOptions` to build with (examples/distribution/build.ts and
+ * scripts/build.ts are two). The rest of the spec is passed to `build()` over
+ * those. Refusals that throw before bundling still run in-process: they never
+ * reach `Bun.build`.
+ *
+ * Like `bun test` itself this is for a checkout: the child runs the build
+ * module under the bun that runs the tests. Never import it from the program.
+ */
+
+import { spawnSync } from "node:child_process";
+import { dirname, isAbsolute } from "node:path";
+import { build, type BuildOptions, type BuildResult } from "../src/build";
+
+export interface ChildBuild {
+  /** Absolute path of a module exporting `BUILD: BuildOptions`. */
+  readonly module: string;
+  readonly outfile: string;
+  readonly tag?: string;
+  readonly releaseRepo?: string;
+  readonly versionExtra?: string;
+  readonly docsBase?: string;
+}
+
+/** Run one build in a fresh bun; its result, or the child's stderr as the error. */
+export function buildInChild(spec: ChildBuild): BuildResult {
+  if (!isAbsolute(spec.module)) throw new Error(`buildInChild: module must be an absolute path: ${JSON.stringify(spec.module)}`);
+  const r = spawnSync(process.execPath, ["--no-env-file", "--config=/dev/null", import.meta.path, JSON.stringify(spec)], {
+    cwd: dirname(spec.module),
+    encoding: "utf8",
+    timeout: 170_000,
+  });
+  if (r.status !== 0) throw new Error(`build in a child bun failed (status ${r.status}, signal ${r.signal}):\n${r.stderr}`);
+  return JSON.parse(r.stdout) as BuildResult;
+}
+
+if (import.meta.main) {
+  const { module, ...rest } = JSON.parse(process.argv[2] ?? "{}") as ChildBuild;
+  const { BUILD } = (await import(module)) as { BUILD?: BuildOptions };
+  if (BUILD === undefined) throw new Error(`${module} does not export BUILD`);
+  const r = await build({ ...BUILD, ...rest });
+  process.stdout.write(`${JSON.stringify(r)}\n`);
+}

package/testing/fake-runner.ts

@@ -0,0 +1,23 @@
+/**
+ * fake-runner.ts — a `Runner` that records every call and answers from a
+ * function, so a test injects one instead of stubbing PATH
+ * (src/runtime/process.ts holds the real adapter and the interface).
+ */
+
+import type { RunOptions, RunResult, Runner } from "../src/runtime/process";
+
+export type FakeRunner = Runner & { calls: Array<{ argv: readonly string[]; opts: RunOptions }> };
+
+/** A Runner that records every call and answers from `respond`. */
+export function createFakeRunner(
+  respond: (argv: readonly string[], opts: RunOptions) => RunResult | Promise<RunResult>,
+): FakeRunner {
+  const calls: FakeRunner["calls"] = [];
+  return {
+    calls,
+    async run(argv, opts) {
+      calls.push({ argv, opts });
+      return respond(argv, opts);
+    },
+  };
+}

package/testing/index.ts

@@ -0,0 +1,16 @@
+/**
+ * `eris/sdk/testing`: the test helpers a distribution's own suites reuse
+ * instead of copying (docs/dev/PLUGINS.md#testing-a-distribution).
+ *
+ *   - `createFakeRunner`, `FakeRunner`: a `Runner` (eris/sdk) that records its
+ *     calls and answers from a function;
+ *   - `buildInChild`: `build()` in a child bun, one process per compile.
+ *
+ * Separate from `eris/sdk` and outside src/ so a binary never carries it: the
+ * `runtime-imports-no-testing` rule keeps src/, ts/ and plugins/ from importing
+ * it, and `distribution-imports-sdk-only` does the same for a distribution's
+ * source in this repository.
+ */
+
+export { buildInChild, type ChildBuild } from "./build-child";
+export { createFakeRunner, type FakeRunner } from "./fake-runner";

package/ts/lib/eris-fail.ts

@@ -0,0 +1,180 @@
+/**
+ * eris-fail.ts — the `ERROR`/`slug:`/`fix:`/`docs:` failure block, in TS.
+ *
+ * The block predates this module: an earlier Bash implementation of eris
+ * printed it (`eris::report`), and this module reproduces it BYTE FOR BYTE
+ * for the same inputs, because `docs/OUTPUT-CONTRACT.md` §4 says the shape is
+ * a **contract**: consumers line-prefix-parse it, and a re-implementation is
+ * required to *reproduce* the grammar, never to re-derive it.
+ * `tests/eris-fail.test.ts` proves byte-identity against what that Bash
+ * implementation printed, captured in a real bash subprocess and frozen
+ * (tests/helpers/frozen-oracle.ts) — not by eyeballing the two
+ * implementations side by side.
+ *
+ * The grammar (docs/OUTPUT-CONTRACT.md §4), reproduced here exactly:
+ *
+ *   ERROR <what failed>
+ *   slug: <slug>
+ *   fix: <line>            — zero or more, one per line of the fix text
+ *   docs: <local path>     — $ERIS_HOME/<relpath>
+ *   docs: <github url>     — <docs base>/<relpath>
+ *
+ * The docs base is https://github.com/sibylline-labs/eris/blob/main unless a
+ * distribution named its own: baked by `build({ docsBase })` (src/build.ts), or
+ * handed to `runProgram({ identity })` for a run from source (`identity()` in
+ * src/runtime/home.ts).
+ *
+ * All on stderr; stdout is never touched by anything in this file. Field
+ * order is fixed, every prefix carries its single trailing space, and the
+ * two `docs:` lines are always both present (local first). `<relpath>`
+ * defaults to `docs/ERRORS.md#<slug>`, exactly matching the Bash
+ * `eris::report`'s `docs="${4:-docs/ERRORS.md#$1}"`.
+ *
+ * The `fix:` line-splitting mirrors a bash quirk deliberately, not
+ * accidentally: `eris::report` feeds `$fix` through
+ * `<<< "$fix"` into a `while IFS= read -r _line || [[ -n "$_line" ]]`
+ * loop. A here-string ALWAYS appends one `\n` to its content before
+ * feeding it to the loop, so the loop's real input is `${fix}\n` — and
+ * `read` terminates the instant it hits EOF with a truly empty buffer,
+ * never on the placeholder `\n` it appended. Reproducing that requires the
+ * same transform: append one `\n`, split on `\n`, and drop exactly the
+ * one trailing empty element the appended `\n` introduces (see
+ * `splitFixLines` below). That transform is equal to a plain
+ * `fix.split("\n")` for every non-empty `fix` (a trailing `\n` yields one
+ * trailing empty `fix: ` line either way — mutation-checked); the
+ * only case that needs care is the EMPTY fix, which emits no `fix:` line at
+ * all. `tests/eris-fail-golden.test.ts` compares every documented slug,
+ * including a trailing-newline fix and an empty fix, against the real bash.
+ */
+
+import { docsRoot, identity, installRoot, installRootIsUnwritten } from "../../src/runtime/home";
+
+export interface ErisFailureInput {
+  /** Stable machine key, `^[a-z0-9]+(-[a-z0-9]+)+$` — a `docs/ERRORS.md`
+   *  heading anchor. `tests/errors-doc.test.ts` harvests every `slug: "…"`
+   *  literal and fails when its heading is missing. */
+  slug: string;
+  /** The `ERROR <what>` line's message. Never a secret value — name the
+   *  slot/path being resolved, per `docs/OUTPUT-CONTRACT.md` §4. */
+  what: string;
+  /** Zero or more `fix:` lines, `\n`-joined — mirrors `eris::report`'s
+   *  third positional exactly (multi-line fixes are literal, indentation
+   *  included). Omit or pass `""` for no fix lines at all. */
+  fix?: string;
+  /** Repo-relative doc path, optionally with a `#anchor`. Defaults to
+   *  `docs/ERRORS.md#<slug>`, same as bash's `"${4:-docs/ERRORS.md#$1}"`. */
+  docs?: string;
+}
+
+/**
+ * `$ERIS_HOME`: `ERIS_DIR` wins when set; otherwise the install root (src/runtime/home.ts): the
+ * checkout this file sits in, a distribution's own root, or a compiled binary's
+ * asset home. The local `docs:` line names the doc under that root, or under this
+ * package's when a distribution run from source does not carry it (`docsRoot`), so it
+ * names a file that exists every way eris runs.
+ */
+export function erisHome(env: Record<string, string | undefined> = process.env): string {
+  const override = env.ERIS_DIR;
+  if (override && override.length > 0) return override;
+  return installRoot();
+}
+
+/**
+ * Split a `fix:` block into its per-line renderings, reproducing
+ * `eris::report`'s here-string + `read` loop byte for byte (see file
+ * header). Returns `[]` for an absent/empty `fix` — matching bash's
+ * `if [[ -n "$fix" ]]` guard, which skips the loop entirely rather than
+ * emitting one empty `fix: ` line.
+ */
+export function splitFixLines(fix: string | undefined): string[] {
+  if (!fix || fix.length === 0) return [];
+  // Simulate the here-string's appended `\n`, split, then drop the ONE
+  // trailing empty element that append introduces — never a real line.
+  const withTrailingNewline = `${fix}\n`;
+  const parts = withTrailingNewline.split("\n");
+  parts.pop();
+  return parts;
+}
+
+/** The failure block's lines, in order, with NO trailing `\n` on any of
+ *  them — `renderFailureBlock` is what adds one per line. Exposed
+ *  separately so a test can assert on individual lines without
+ *  re-parsing the joined block.
+ *
+ *  With no local copy of the docs to name (`home` null, or the install root of a
+ *  compiled binary whose asset home could not be written, `eris-cache-unwritable`),
+ *  the first `docs:` line is the repo-relative
+ *  path, so the block keeps its two `docs:` lines and the GitHub one stays the
+ *  readable one. */
+export function failureLines(input: ErisFailureInput, home: string | null): string[] {
+  const lines: string[] = [];
+  lines.push(`ERROR ${input.what}`);
+  lines.push(`slug: ${input.slug}`);
+  for (const fixLine of splitFixLines(input.fix)) {
+    lines.push(`fix: ${fixLine}`);
+  }
+  const docsRel = input.docs && input.docs.length > 0 ? input.docs : `docs/ERRORS.md#${input.slug}`;
+  const local = home === null || (installRootIsUnwritten() && home === installRoot()) ? null : home;
+  lines.push(`docs: ${local === null ? docsRel : `${docsRoot(local, docsRel)}/${docsRel}`}`);
+  lines.push(`docs: ${identity().docsBase}/${docsRel}`);
+  return lines;
+}
+
+/** The full block, `\n`-terminated on every line — byte-identical to what
+ *  `eris::report`/`eris::fail` writes to stderr for the same inputs. */
+export function renderFailureBlock(input: ErisFailureInput, home: string | null = erisHome()): string {
+  return failureLines(input, home)
+    .map((line) => `${line}\n`)
+    .join("");
+}
+
+/** A write-only stream: process.stderr, or a capture in tests. */
+export interface FailureSink {
+  write(chunk: string): unknown;
+}
+
+/**
+ * The TS `eris::report`: write the block and RETURN 1
+ * instead of exiting, for a caller that owns something which must run after
+ * the failure (e.g. a failed WAL result after a failed write). Prefer
+ * `emitFailureAndExit`; the caller of this adds its own summary.
+ * `tests/eris-fail-golden.test.ts` pins it against every documented slug.
+ */
+export function reportFailure(
+  input: ErisFailureInput,
+  home: string = erisHome(),
+  sink: FailureSink = process.stderr,
+): 1 {
+  sink.write(renderFailureBlock(input, home));
+  return 1;
+}
+
+/** Write the block to stderr and exit 1 — the TS `eris::fail` equivalent.
+ *  Stdout is never touched (§1 of the output contract: a failure writes
+ *  nothing to stdout). */
+export function emitFailureAndExit(
+  input: ErisFailureInput,
+  home: string = erisHome(),
+  sink: FailureSink = process.stderr,
+  exit: (code: number) => never = (code) => process.exit(code),
+): never {
+  sink.write(renderFailureBlock(input, home));
+  return exit(1);
+}
+
+/**
+ * The `WARN` line `eris yak` emits for its environment/config/
+ * transport outcomes: concise, on
+ * stderr, exit 0 — never the four-line failure block, which is reserved
+ * for agent misuse. Two lines, not a bare `WARN <reason>`: the slug alone
+ * is what makes an unset-token/unreachable-endpoint/timeout warning
+ * machine-legible on stderr without promoting it to the exit-1 failure
+ * contract, and `docs/ERRORS.md`'s per-slug headings apply.
+ */
+export function renderWarnLines(reason: string, slug: string): string {
+  return `WARN ${reason}\nslug: ${slug}\n`;
+}
+
+export function emitWarn(reason: string, slug: string): void {
+  process.stderr.write(renderWarnLines(reason, slug));
+}

package/ts/lib/pool.ts

@@ -0,0 +1,63 @@
+/**
+ * pool.ts — env-driven concurrency/deadline resolution, and the in-process
+ * bounded-concurrency runner.
+ *
+ * `ERIS_BATCH_CONCURRENCY` caps how many tasks run at once and
+ * `ERIS_BATCH_TIMEOUT` (seconds) bounds each one. An unset, non-numeric, zero
+ * or negative value CLAMPS to the default rather than disabling the bound:
+ * a typo in an env var must never turn a large batch into an unbounded
+ * fan-out.
+ */
+
+/** Digits only — no sign, no decimal point. An empty, non-numeric, zero or
+ *  negative value clamps to 8 rather than disabling the cap. */
+export function resolveConcurrency(raw: string | undefined): number {
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw);
+    if (n > 0) return n;
+  }
+  return 8;
+}
+
+/** Same integer-seconds grammar, converted to milliseconds for `AbortSignal`.
+ *  Defaults to 60 seconds. Invalid
+ *  input clamps to the default rather than producing NaN (which would mean
+ *  "no deadline at all" — the opposite of the safety property a timeout
+ *  exists to provide). */
+export function resolveDeadlineMs(raw: string | undefined): number {
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw);
+    if (n > 0) return n * 1000;
+  }
+  return 60_000;
+}
+
+/**
+ * Run `worker` over every item in `items`, at most `concurrency` in flight
+ * at once, preserving input order in the returned array regardless of
+ * completion order. A thrown worker error propagates (rejects the whole
+ * pool) rather than being swallowed — callers that want per-item
+ * ok/error/absent results encode that in R itself, so a THROW here always
+ * means a programming error, not a classified task failure.
+ */
+export async function runPool<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  if (items.length === 0) return results;
+
+  let next = 0;
+  async function runner(): Promise<void> {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await worker(items[i] as T, i);
+    }
+  }
+
+  const workerCount = Math.max(1, Math.min(concurrency, items.length));
+  await Promise.all(Array.from({ length: workerCount }, () => runner()));
+  return results;
+}