Using the Foretify Linter

The Foretify Linter identifies problematic use of the OSC2 language. You can use the linter to enforce best practices for code used with Foretellix scenarios and libraries.

Problematic uses of OSC2 are defined as a list of named rules. See Foretify Linter rules for a description.

Note

The linter only reviews instantiated code. For example, if you define a scenario but don't invoke it, the linter does not review the scenario definition.

To invoke the linter, you invoke Foretify with the --lint error or --lint warn option. The lint level you specify applies to all linter rules. If a linter violation with a severity level of error occurs, no OSC2 files are loaded. See Activating the linter for more information about these options.

If you want to specify a lower severity level for a named rule, you can create a linter configuration file and load the file using the --lint_config <config-file> invocation option. For example, if you want to see a warning message for all linter rules except LINT_STANDARD_NAMING, you should create a configuration file that sets the severity level for that rule to IGNORE and invoke Foretify with the --lint warn option. See Configuration file syntax to learn how to set up the configuration file.

If you want to specify a lower severity level for a specific occurrence of a rule violation, you can use the structured comment ##! @lint <lint-level> to mark the line in the OSC2 file that triggers the violation. See Downgrading the severity of specific linter rule violations for information on how to do this.

Note

You cannot use either the configuration file or the structured comment ##! @lint to set a higher severity level. For example, if you set the severity level of LINT_STANDARD_NAMING to ERROR in the configuration file and invoke Foretify with the --lint warn option, any violation of that rule will have a severity level of WARN, unless the line of OSC2 code that triggers the violation is marked with ##! @lint ignore.

The following table shows the interactions between a linter configuration file and the <lint-level> invocation option. The first column shows a configuration rule and its level. The other columns show what happens if the lint-level at invocation is error, warn, and ignore, respectively.

Configuration file rule and level	`--lint error`	`--lint warn`	`--lint ignore`
Rule 1: LEVEL: IGNORE	IGNORE	IGNORE	IGNORE
Rule 2: LEVEL: WARN	WARN	WARN	IGNORE
Rule 3: LEVEL: ERROR	ERROR	WARN	IGNORE
Rule 4: not specified	ERROR	WARN	IGNORE

All rules not included in the configuration file will have the linter level specified using the --lint <lint-level> option.

Activating the linter

Syntax

foretify --lint <lint-level> [--lint_config <config-file>] --load <osc-file>

Options

<lint-level>

Is one of the following:

ignore: the linter is not activated. This is the default mode.
warn: the linter is activated and a warning is issued for every violation. In this mode lint violations do not cause the load process to fail.
error: the linter is activated and an error is issued for every violation. In this mode, unless the file is completely free of lint violations, all violations are reported and the load process fails.

<config-file>

An optional text file specifying a list of named rules and their severity level. If the configuration file specifies a rule name or level that does not exist, an error is flagged and the load fails.

<osc-file>

The OSC2 files that are to be passed to the linter.

Configuration file syntax

The linter configuration file is a text file. Each configuration has two lines of name: value pairs: one to specify the severity LEVEL and the other to specify the MESSAGE (the named rule). Capital letters are required.

Example linter config file

-
    LEVEL: IGNORE
    MESSAGE: LINT_ABSOLUTE_SPEED
-
    LEVEL: ERROR
    MESSAGE: LINT_RELATIONAL_EGO_DRIVE
-
    LEVEL: WARN
    MESSAGE: LINT_ACTOR_FIELD_NAME
-
    LEVEL: ERROR
    MESSAGE: LINT_SNAKE_CASE

The following example shows how to invoke the linter to identify problematic code in an OSC2 file.

Shell command: linter invocation example

$ foretify --load mytest.osc --lint error --lint_config lntcfg.txt
Checking license...

Initializing Foretify runtime...

[INFO] Compilation done, 0 errors and 0 warnings reported

[0.000] [MAIN] Using map $FTX_PACKAGES/maps/M73_FTX_highway.xodr

Linter violations:
Severity  Rule     Details  
WARN      lint_actor_field_name   Actor's field name 'car1' of type 'vehicle' is not in the format '[<name>_]<type>[_<count>]'

Foretify>

Displaying the linter rules

The show lint_rules command displays all the currently defined linter rules.

The output of the command is a table with the following format for each rule:

Rule name
Rule description
Rule activation level (ignore, warn, error)

Downgrading the severity of specific linter rule violations

You can intentionally use a style that is discouraged by the linting rules and downgrade the severity of the violation to either warn or ignore. For example, if you want to see a warning for all LINT_ABSOLUTE_SPEED violations except one or two lines of OSC2 code that trigger that violation, mark those lines with ##! @lint ignore lint_absolute_speed and invoke Foretify with --lint warn.

To downgrade a linter rule violation, use the structured comment @lint:

OSC2 code: override linter rule syntax

##! @lint ignore [<rule-name>[, <rule-name>],...]

If no rule name is specified, the lint directive applies to all the rules.

OSC2 code: override linter rule example

extend top.main:
    Car1: vehicle ##! @lint ignore
    do serial:
        sut.car.drive() with:
            speed(50kph, at: all) ##! @lint ignore lint_absolute_speed