@spec check_deadline!(JustBash.Limit.Deadline.t() | JustBash.t() | nil) :: :ok

Raise ExceededError if an armed deadline has passed.

Accepts a Deadline, a JustBash struct carrying one, or nil for "no bound". Counting limits cannot see a loop that burns time without doing countable work, which is how both of this project's historical hangs escaped every other bound.

@spec check_expansion_words!(JustBash.t(), non_neg_integer()) :: :ok

Bound how many words one word may expand into. Raises ExceededError if exceeded.

The step counter cannot see this: a word is a single step regardless of the size of the list it names, so {1..1000000} — twelve characters — is one step and a million words. That is counted work, not merely slow work, so the bound is :max_steps rather than the wall clock; the clock is checked alongside it so a budget large enough to permit the list still cannot be spent entirely on building it.

Call this with the running count as the list is produced, not with the finished list's length — the point is to refuse before the memory is spent.

@spec check_file_size!(JustBash.t(), String.t() | non_neg_integer()) :: :ok

Check file data size before writing. Raises ExceededError if too large.

Accepts the data binary, or a byte count for append-style writes where the resulting size is known without materializing the content.

@spec check_regex_size!(t() | nil, String.t()) :: :ok

Check regex pattern size only. Use compile_regex/3 when you also need compilation.

For call sites that need custom compilation logic (e.g. grep's flag handling, sed's BRE-to-ERE conversion), call this directly.

@spec check_value_size!(JustBash.t(), String.t() | non_neg_integer()) :: :ok

Check a value's size before keeping it. Raises ExceededError if too large.

Accepts the data binary, or a byte count so callers can refuse a concatenation or replacement before it is built — see concat!/3 and replace!/5.

@spec compile_regex(t() | nil, String.t(), String.t() | [atom()]) ::
  {:ok, Regex.t()} | {:error, term()}

Check regex pattern size and compile. Raises ExceededError if pattern too large.

Centralizes the check-then-compile pattern used across commands (grep, sed, awk, jq, etc.). Accepts a limits struct (not a full bash struct) so it can be called from command internals that don't carry the full struct.

@spec concat!(JustBash.t(), binary(), binary()) :: binary()

Concatenate two binaries, raising ExceededError if the result would exceed :max_value_bytes.

The check is on the sum of the sizes, so the oversized result is never allocated — a single v=${v}${v} of a multi-gigabyte value is the hole this closes. Call this as word parts are joined, not with the finished binary.

@spec deadline(t() | nil) :: JustBash.Limit.Deadline.t() | nil

Arm a deadline for one top-level execution, or nil when limits are off.

Call this once per JustBash.exec/2 and carry the result; check_deadline!/1 then costs a single monotonic clock read and an integer comparison, so it is affordable on the interpreter's statement loop.

@spec defaults() :: t()

Returns the default limits.

@spec enforce_deadline(Enumerable.t(), JustBash.Limit.Deadline.t() | nil) ::
  Enumerable.t()

Wrap an enumerable so each element it yields first checks deadline.

Used by JustBash.Commands.Seq: a whole command is a single step as far as the step counter is concerned, so without this seq 1 100000000 is unbounded. Commands whose loop is not already an enumerable call check_deadline!/1 directly instead — see JustBash.Commands.Find.

@spec new(atom() | keyword() | false) :: t() | nil

Build limits from a preset atom, keyword list, or false to disable.

@spec replace!(JustBash.t(), Regex.t(), binary(), binary(), keyword()) :: binary()

Replace matches of regex in str with replacement, raising ExceededError if the result would exceed :max_value_bytes.

The check is on the projected size from match lengths, so the oversized result is never allocated — a single ${v//a/$r} of cap-sized v and r is the hole this closes. Call this instead of Regex.replace/4.

@spec step!(JustBash.t()) :: JustBash.t()

Increment step counter. Raises ExceededError if limit is reached.

@spec track_exec_depth!(JustBash.t()) :: JustBash.t()

Increment exec depth and track the high-water mark. Raises ExceededError if limit is exceeded.

@spec track_output!(JustBash.t(), non_neg_integer()) :: JustBash.t()

Track output bytes. Raises ExceededError if limit is reached.