retrofit validate
Validate retrofit.toml, project layout, and the oplog
Synopsis
Usage:
retrofit validate [flags]
Options
Flags:
--all report every registered schema, as with no --schema (and satisfying RETROFIT_REQUIRE_EXPLICIT_SCHEMA)
--allow-database-apply [apply context] with --history, attest that CI applies the range to a database before it lands: the opaque-body check lists its findings as advisory and does not fail
--allow-unmerged-fork report an unmerged fork as an advisory and exit 0; apply-risk hazards, seal-integrity refusals and standing violations still fail the run
--every-commit with --history, validate every commit of the PR in the bundle, not only the candidate
--fail-on-apply-risk fail (exit 2) on the apply-risk hazards in the migration window since the latest Seal (or the cut --from names): validating-fk, validating-check, add-not-null and a column-type change (a cast) that rewrites the table or scans it for an index or check, on a table that may hold rows; add-unique stays advisory, and so does a cast whose recovery retrofit does not vouch for
--from string with the apply-risk gate, judge the window (<cut>, head] in place of (latest Seal, head]; an anchor (root, last, seal, with ^ or ~N) or an opid prefix
-h, --help help for validate
--help-all show extended help (vocabulary, semantics, caveats)
--history string check the history bundle at <dir> (written by the CI snippet; retrofit runs no git)
--schema <name> report only registered schema <name>'s findings; repeat it for each schema to report (every registered oplog is still read)
Global options
Global Flags:
--as string output mode: text | json (default "text")
-C, --chdir string treat <dir> as the working directory for the entire run
--config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
-f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
--no-consolidate render every advisory occurrence instead of collapsing repeats
-q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
-v, --verbose reveal info-tier advisories on stderr
Docs: https://docs.retrofit.sh/wip/commands/retrofit-validate/
retrofit validate --help-all adds:
Extended help:
What this verb checks:
- retrofit.toml structure: unregistered-schema-in-directory-scope,
directory-scope-duplicate-key, multiple-schemas-share-dir.
- oplog placement and integrity: schema-stray-oplog,
oplog-missing-at-recorded-path, oplog-unreadable,
seal-digest-mismatch, sealed-oplog-unparsable.
- oplog syntax: a line that does not parse fails the run wherever
it falls, under the parser's code; merge conflict markers are
named as such.
- replay: the log is replayed against its op rules and its
engine-version pin, and a rule violation fails the run. Syntax
newer than this build's syntax level refuses syntax-not-available
(exit 2) at any pin; an op the pin is too old for refuses
unsupported-on-engine-version (exit 2). An unknown header or op
key, or a newer retrofit-model-version, reports unverifiable
(exit 2) when nothing else fails.
- cross-schema references: a body that names an element no
registered schema resolves fails the run under
rule-exists-and-alive. The holders must be live at the tip.
- forks: a fork is two or more ops sharing the same prev=, arising
when concurrent branches each append onto the same op and a git
merge concatenates both appends into one file. `validate` reports
a fork as schema-fork-unmerged and, by default, fails the run
(exit 2, code structural-gate) on an unmerged fork; pass
--allow-unmerged-fork to report without failing. Either way,
`validate` does not resolve a fork. Run
`retrofit reconcile --help-all` for the block / bias / strictness
vocabulary reconcile uses to close one.
Also prints a resolution preview: every (scope-dir, schema, source)
triple the config resolves to, so a directory-scope ambiguity is
visible before it surfaces as a load-time error elsewhere.
Scope: --schema <name>, repeatable, reports only the named schemas'
findings; no flag, or --all, reports every registered schema. With
several registered, the run opens by stating its scope. Every oplog is
still read, so an oplog that is missing, unreadable or unparsable, a
sealed range whose digest no longer matches, and a reference no schema
resolves fail the run whatever the scope. A --from opid names a place
in one schema's oplog, so pass --schema for that schema with it.
History mode: --history <dir> runs the history checks over a history
bundle, the files each check reads at each commit of a pull request,
which a CI job writes (retrofit runs no git). A file a check needs that
the bundle lacks refuses history-bundle-missing, naming each one, and
a bundle it cannot trust refuses history-bundle-refused before any
check runs. --every-commit validates every commit of the pull request,
not only the candidate. The CI guide on the docs site shows the script
that writes the bundle.