--check-version-bounds

import { Aside } from ‘@astrojs/starlight/components’;

--check-version-bounds is a fast-path flag that lets shell wrappers (e.g. opaquev/ov-scan-action) and CI integrations gate behavior on the installed ov binary’s semver version. It exits with a deterministic code (0/1/2) and a diagnostic message on stderr — no other ov work runs.

This is a wrapper-friendly primitive: prefer it over shell-level `sort -V` (Linux-only on default macOS) or hand-rolled semver comparison. The check runs against the version stamped into the binary at build time via `goreleaser` ldflags.

---

Usage

ov --check-version-bounds --min-ov-version <semver> --max-ov-version <semver>

When --check-version-bounds is set, the binary runs the version check and exits — even if a subcommand is also on the command line. Chain via shell && if you want the subcommand to run only after the gate passes.

---

Flags

Flag	Default	Description
--check-version-bounds	false	Trigger the bounds check. Required to opt in.
--min-ov-version <semver>	""	Minimum acceptable version (inclusive). Empty = no minimum.
--max-ov-version <semver>	""	Maximum acceptable version (inclusive). Empty = no maximum.
--allow-binary-version	false	Override the bounds check; exit 0 with stderr note. Mirrors the action input.

---

Exit codes

Code	Meaning
0	Version in range, override active, or development build (version == "dev").
1	Version out of range — below --min-ov-version or above --max-ov-version.
2	Malformed semver in any of the three: binary version, MIN, MAX.

---

Examples

CI gate: require ov ≥ 0.10.0

ov --check-version-bounds --min-ov-version 0.10.0 \
  && ov scan --format=sarif > findings.sarif

If the installed ov is 0.9.x, the gate exits 1 before ov scan runs. The && shell operator stops the pipeline — no findings file is written.

Pin to an exact version range

ov --check-version-bounds \
  --min-ov-version 0.10.0 \
  --max-ov-version 0.10.99 \
  || { echo "ov binary outside supported range"; exit 1; }

Override (use sparingly — fork-PR contexts disable this)

ov --check-version-bounds \
  --min-ov-version 1.0.0 \
  --allow-binary-version
# exit 0 with stderr: "version-bound check overridden by --allow-binary-version"

---

Semver semantics

The check uses Masterminds/semver/v3 which implements Semantic Versioning 2.0.0 precisely:

• Build metadata is ignored (per §10): 0.10.0+build.42 and 0.10.0+build.99 compare equal.
• Pre-release identifiers are ordered below releases (per §11): 0.10.0-alpha.1 < 0.10.0. A binary tagged 0.10.0-rc.1 will fail --min-ov-version 0.10.0.

If you want to allow pre-releases for testing, set the floor below the release: --min-ov-version 0.10.0-0.

---

Development builds

Local builds without goreleaser ldflags ship version = "dev". The bounds check skips with a stderr note:

development build, version-bound check skipped

Exit code is 0. This keeps make build developer ergonomics intact — you don’t need to pass version-bound flags during local iteration.

---

Why this lives in the binary, not the wrapper

Pushing semver comparison into the signed ov binary:

• Eliminates Linux-only sort -V shell traps (BSD sort on default macOS lacks -V).
• Pushes complexity into already-trusted code — the binary’s signature is the trust anchor; the wrapper script just shells out.
• Cross-platform — Windows, BSDs, and macOS all work identically.
• Single source of truth for semver semantics — no risk of the wrapper and the binary disagreeing on pre-release ordering.

This is consumed primarily by opaquev/ov-scan-action (Linear OV-239), which uses it to enforce min-ov-version / max-ov-version action inputs without rolling its own semver parser.

---

Related

• ov scan — the scanner this gate typically protects.
• Installation — how to install a specific version.
• Linear: OV-244 (this flag), OV-239 (consuming action).