oxo-flow lint#
Run best-practice linting checks on a .oxoflow file.
Usage#
Arguments#
| Argument | Description |
|---|---|
<WORKFLOW> |
Path to the .oxoflow workflow file |
Options#
| Option | Short | Default | Description |
|---|---|---|---|
--strict |
— | — | Treat warnings as errors (non-zero exit) |
--ai |
— | — | Enable AI-powered semantic linting |
--verbose |
-v |
— | Enable verbose (debug-level) logging |
--quiet |
— | — | Suppress informational output — the version banner is omitted; lint diagnostics and the summary are printed regardless (verified: output is byte-identical with --quiet) |
--no-color |
— | — | Disable colored output |
--json |
— | — | Output machine-readable JSON to stdout |
Examples#
Run standard linting#
Run strict linting#
Output#
oxo-flow v0.32.0 — Rust-native bioinformatics pipeline engine
warning [W003]: rule has no description (rule: bwa_align)
hint: add description = "Brief one-line description of what bwa_align does" to this rule
info [W004]: rule has a shell command but no log file specified (rule: bwa_align)
hint: add log = "logs/bwa_align.log"
info [W007]: leaf rule (no dependents) could be marked as target = true (rule: fastqc)
hint: add target = true to this rule
info [W025]: rule uses deprecated rule-level threads/memory (rule: bwa_align)
hint: replace `threads = N` / `memory = "8G"` with `resources.threads = N` / `resources.memory = "8G"` under this rule
Summary: 0 errors, 1 warning, 3 info
Each diagnostic prints a hint: line (when a suggestion exists) showing
the fix, matching the style of validate and run output.
W007
suggests target = true: a rule marked as a target is built by default
when oxo-flow run is invoked without an explicit -t, so marking the
final leaf rules (like fastqc above) makes them part of the default
run — see Workflow Format: Priority and Targeting.
W025 flags the deprecated rule-level threads = N / memory = "8G"
fields (superseded by [rules.resources] in v0.4) so old workflows
surface the migration instead of silently keeping their old settings —
see Workflow Format: Rule resources.
W031 flags a consumer rule that reads the output of a when-gated
producer without a when gate of its own: when the producer's gate is
off, its files never appear and the consumer's inputs cannot be resolved
at plan time (dry-run input ✗) or the run fails outright. Wildcard
templates match after canonicalizing every {...} placeholder, and
fully literal paths match literally — a literal input of a gated
producer is the same hazard. The repair is either a matching when gate
on the consumer or splitting it into when-gated variants (the
multiqc/multiqc_pseudo idiom). Consumers that declare their
tolerance for a missing producer are not flagged: optional = true /
"any" rules, input_groups disk-discovery fallbacks, and consumers
that already carry any when gate.
W033 flags two rules that write the same output path — including
differently-named wildcards over the same template (variants/{smp}.vcf
vs variants/{sample}.vcf) and identical literal paths. The engine does
not refuse to run: both rules execute and the second to finish silently
overwrites the first (verified live with a run reporting
success while both colliding rules executed), so downstream rules consume
the wrong file. The repair is distinct output directories per writer —
or a when gate when the two rules are mutually exclusive alternatives
(the wgs_coverage/wes_coverage idiom). Multi-producer outputs remain
a supported feature, so this is a warning, not an error. {config.*}
placeholders are resolved against the parsed config before the templates
are compared, so {config.out_dir}/{sample}.vcf collides with its literal
counterpart results/{sample}.vcf when out_dir = "results" — and does
not collide with {config.alt_dir}/{sample}.vcf when the values differ.
When both writers carry meaningful when gates that are complementary
empty-string checks on the same expression — X != '' on one and
X == '' on the other (the paired/tumor-only
mutect2_paired/mutect2_tumoronly shape) — each rule runs exactly when
the other does not, so the pair can never race and the collision is not
reachable at runtime. W033 then downgrades to an info note naming the
shared expression ("... their when gates are complementary on 'X' —
collision is not reachable at runtime") instead of the warning. The
detection is deliberately narrow: a single top-level ==/!= whose
right side is the empty-string literal '' or "" and whose left side
is the same bare config.<name> or wildcard.<name> reference on both
sides. These are the only left-hand forms the executor compares with
exact complement semantics — compound conditions (&&/||),
comparison operators
other than ==/!=, function-call or unqualified-identifier left
sides, different expressions, non-empty or unquoted
right-hand sides, and pairs where either writer is ungated all keep the
plain warning — a syntactic complement there would not prove a runtime
one (a shared disjunct short-circuits both gates to true; anything the
executor cannot parse as a reference falls through to its default-true
verdict).
See
Troubleshooting → Output collisions.
W034 flags an {input[N]} / {output[N]} placeholder whose index is out
of range, or a named {input.key} / {output.key} whose key the rule
does not declare. The substitution loop only renders indices 0..len
(list-form: declaration order; map-form: keys in sorted order; dir-form:
the single entry), and only renders named references for declared keys —
anything else survives rendering as literal brace text, so the tool is
invoked with a path like {input[5]} and fails with an unrelated
"No such file" error that hides the real mistake. The repair depends on
the input shape: use an in-range index (map-form indices follow the
rule's sorted keys, not the text order), switch to the bare {input} /
{output} form to interpolate all entries, or — preferred for
role-bearing IO — declare a map and use named access (tumor = "..." +
{input.tumor}), which also survives reordering. Lines that are comments
in the rendered script are exempt, and script paths are checked the
same way as inline shell.
W032 flags a [config] key whose name looks like a secret
(token, secret, passwd, password, credential, api_key,
access_key, private_key, ssh_key, key — matched at word/segment
boundaries, so names that merely contain these as a substring, like
tokenize or password_length_hint, are not flagged) but is not
declared sensitive: its value then lands in plaintext in command
records, stderr tails, and the checkpoint — credential leakage on shared
clusters and in CI artifacts. The repair is the declaration itself:
Declared-sensitive keys are env-routed and masked on disk, so W032
never flags them — see
[config] — Configuration Variables.
to declare the glob in input = [...] — glob inputs are compiled by
the DAG builder and linked to every matching producer output, so they
create real edges — or, for gather/fan-in steps, to list the files via
expand_inputs. Pattern arguments (find data -name '*.tmp') and
cleanup commands (rm -rf build/*) are not data reads and are not
flagged.
W036 flags a rule that
declares input_function. The field is parsed and round-tripped, but
the engine performs no dynamic input resolution — the function is
never called, so the rule's input list stays exactly as declared.
Because input_function also suppresses W035's glob-only heuristic,
an undeclared-glob rule would otherwise look silently safe; W036
fires alongside so the missing dynamic behavior is never invisible.
The repair is to declare the inputs statically (input = [...],
glob inputs, or expand_inputs).
W037 flags a rule whose
resource_hint sets runtime or io_bound. Both fields are parsed
and round-tripped, but nothing consumes them — the memory estimator
reads only input_size and memory_scale. The repair is to declare
enforced limits instead (resources.time_limit, resources.memory,
resources.threads); the reserved hints stay legal TOML so external
tooling can keep writing them.
W039 flags a dotted
{namespace.key} placeholder whose namespace the engine does not
recognize — for example {metadata.batch} where {meta.batch} was
meant. Bare {token} wildcards already get an unknown-wildcard
warning and {input.…}/{output.…} mistakes have their own W034
checks, but an unrecognized dotted namespace used to fall through
every guard: the token renders as literal brace text and the tool
fails on input that looks valid. The diagnostic suggests the closest
recognized namespace when the typo is a prefix-extended or truncated
form (metadata → meta, conf → config); shell brace text like
awk '{print $1}' and comment lines are not flagged.
W040 flags a rule with no
runnable command: shell is missing or empty/whitespace-only and no
non-empty script is declared. This is the lint mirror of
E022 — the engine skips
such a rule at run time (“no shell or script defined”), so the workflow
validates yet silently does nothing. The classic source is an
oxo-flow import of a Nextflow process whose script: block was not
captured; re-import after upgrading, or add the command by hand.
transform rules are exempt because their command lives in
transform.map/transform.combine.
W041 flags a rule that
references the sample domain — {sample}, {group}, {wildcard.sample},
{wildcard.group}, or {meta.<column>} — with no binding source. The
rule then runs exactly once and the token stays unbound (the
execution-time placeholder gate rejects the rendered command). The repair
is to bind the domain in input/output and declare its source
([[sample_groups]], [[pairs]], sample_pattern, pairs_pattern,
[[values]], or a scatter) — or, for a deliberate one-instance
{meta.*} read, add singleton = true. singleton silences the LINT
diagnosis only; the execution-time gate still rejects a {meta.*} token
that survives rendering (a one-row metadata table is the supported
constant read; {config.<key>} is the workflow constant). The binding
model is shared with the expansion engine, so:
- a
sample_pattern/pairs_patterndeclaration counts even when lint runs without the data mounted (CI/editor); - a
{meta.*}reference inoutputbinds when the metadata column(s) uniquely key every instance — a constant column (batch_{meta.batch}.tsv) does not fan out and stays flagged (the engine avoids the silent duplicate-output race); - a one-row metadata table is an unambiguous constant read;
singleton = truesuppresses{meta.*}only — a{sample}/{group}survivor is always a defect and stays flagged;- a scatter binds its own variable (a scatter over
pair_iddoes not hide an unbound{sample}); - every free-text field is scanned, including
log,script,benchmark, hooks, env-var values, and string params. Shell${...}parameter expansion and comments are never treated as placeholders.
Notes#
lintis a strict superset ofvalidate: it runs every validate check (parsing, DAG, input existence) plus style linting and secret scanning — runningvalidateseparately afterlintadds nothing- Linting checks for common mistakes, missing metadata, and potential performance issues
- Rules are checked for valid input/output patterns and environment declarations
- Use
--strictto ensure high-quality workflow definitions in production environments
Every finding carries a stable code (E0xx = validation error, W0xx =
lint warning). The full code index with one-line meanings lives in the
Glossary → Diagnostic Codes.