Linting API

Users interact with RefTrace via Starlark, a Python-like language. See the difference between Python and Starlark here.

The API RefTrace exposes is callback-based. Users define “rules” and RefTrace supplies them with a Nextflow module object.

Rules must be of this form:

def rule_name(module):
    # Your rule implementation here
    pass

Behavior is undefined for duplicate rules in the same “rules” file and for rules that don’t accept a single module argument. name can be anything. RefTrace only cares that rules start with rule_ and accept a single module argument.

Other helper functions can be defined in the same file as your rules. The standard built-in Starlark functions are available. RefTrace disables fail and handles output from print.

Rule Output

RefTrace provides three functions for rules to interact with the outside world:

fatal

The fatal(*args) function is used to report linting errors. It stops the execution of the rule in the current module.

fatal("oops")
fatal(module.name, "is missing a directive")

error

The error(*args) function is used to report linting errors. It reports the error but continues execution.

error("oops")
error(module.name, "is missing something but I keep going")

print

The print(*args) function is used to output to the console. It’s useful for debugging and exploring.

print(module)
print(module.path, module.processes)
print(module.processes[0].directives.cpus[0])

Nextflow Module Object

This is the top-level object that rules operate on. It represents a single Nextflow module.

module.path (string)

The absolute path to the module.

module.includes (List[Include])

A list of all the includes in the module.

module.processes (List[Process])

A list of all the processes in the module.

Include Object

include.items (List[IncludeItem])

A list of all the functions, processes, or named workflows being included from the module.

include.module_path (string)

The path to the module being included.

IncludeItem Object

Represents a function, process, or named workflow being included from the module.

item.name (string)

The name of the function, process, or named workflow.

item.alias (string)

The alias of the function, process, or named workflow.

include {foo as bar} from './some/module'

The name would be foo and the alias would be bar.

Process Object

Represents a single Nextflow process.

process.name (string)

The name of the process. Does not include the module path.

process.inputs (Inputs)

The inputs to the process. An object.

process.outputs (Outputs)

The outputs of the process. An object.

process.directives (Directives)

This is an object, not a list. It provides a typed interface to the directives in the process. Each field in the Directives object is a list. For example, a process can have multiple label directives.

Process Inputs Object

The fields map to the type of inputs listed here.

The available fields are:

inputs.vals (List[Val])
inputs.files (List[File])
inputs.paths (List[Path])
inputs.envs (List[Env])
inputs.stdins (List[Stdin])
inputs.tuples (List[Tuple])

Val

var (string)

File

path (string)
arity (string)
stage_as (string)

Path

path (string)
arity (string)
stage_as (string)

Env

var (string)

Stdin

var (string)

Tuple

values (List[Input])

Process Outputs Object

The fields map to the type of outputs listed here.

The available fields are:

outputs.vals (List[Val])
outputs.files (List[File])
outputs.paths (List[Path])
outputs.envs (List[Env])
outputs.stdouts (List[Stdout])
outputs.tuples (List[Tuple])

Val

var (string)
emit (string)
optional (bool)
topic (string)

File

path (string)
emit (string)
optional (bool)
topic (string)

Path

path (string)
arity (string)
follow_links (bool)
glob (bool)
hidden (bool)
include_imports (bool)
max_depth (int)
path_type (string)
emit (string)
optional (bool)
topic (string)

Env

var (string)
emit (string)
optional (bool)
topic (string)

Stdout

emit (string)
optional (bool)
topic (string)

Tuple

values (List[Output])
optional (bool)
topic (string)

Directives Object

The fields map to the directives listed here. See the Nextflow docs for more details about each directive.

accelerator

num_gpus (int)
gpu_type (string)

after_script

script (string)

arch

name (string)
target (string)

array

size (int)

before_script

script (string)

cache

enabled (bool)
deep (bool)
lenient (bool)

cluster_options

options (string)

conda

dependencies (string)

container

name (string)

container_options

options (string)

cpus

num (int)

debug

enabled (bool)

disk

space (string)

echo

enabled (bool)

error_strategy

strategy (string)

executor

executor (string)

ext

version (string)
args (string)

fair

enabled (bool)

label

label (string)

machine_type

machine_type (string)

max_submit_await

max_submit_await (string)

max_errors

num (int)

max_forks

num (int)

max_retries

num (int)

memory

memory (string)

module

name (string)

penv

environment (string)

pod

env (string)
value (string)

publish_dir

path (string)
contentType (bool | None)
enabled (bool | None)
failOnError (bool | None)
mode (string)
overwrite (bool | None)

queue

name (string)

resource_labels

We currently only provide the keys.

keys (List[string])

resource_limits

cpus (int64 | None)
disk (string | None)
memory (string | None)
time (string | None)

scratch

enabled (bool)
directory (string)

shell

command (string)

spack

dependencies (string)

stage_in_mode

mode (string)

stage_out_mode

mode (string)

store_dir

directory (string)

tag

tag (string)

time

duration (string)

dynamic

Directive that has a closure as an argument. RefTrace currently does not try to evaluate closures.

name (string)

unknown

Directive that is not recognized by RefTrace.

name (string)