bslint - BrighterScript Lint

brighterscript is a Roku BrightScript compiler featuring many diagnostics out of the box: syntax check, function calls validation, script imports verification...

bslint is:

a CLI tool to lint your code without compiling your project,
a brighterscript plugin offering additional insights on your code.

Installation

You need Node 10+ and npm or yarn:

# if you don't have a package.json
npm init -y

# install modules
npm install brighterscript @rokucommunity/bslint

Add the plugin to your bsconfig.json file in the root of your project, or create a minimal file like that:

{
    "plugins": [ "@rokucommunity/bslint" ]
}

Command line interface (CLI)

The bslint command will run the BrighterScript compiler without publishing step, only outputing the diagnostics.

Note: the CLI can be used without adding the bslint plugin; you will only get the default brighterscript diagnostics.

npx bslint --help

# lint with default options
npx bslint

or add a npm script in package.json, e.g.:

{
    ...
    "scripts": {
        "lint": "bslint"
    }
    ...
}

and call npm run lint.

Rules

Linting rules can be set in a bslint.json file in the root of your project.

Rules are organised in 3 categories:

"Code style": how the code should look like for consistency
"Strictness": requirement to ensure code safety
"Code flow": tracks the code flow to identify risky patterns

Default rules:

{
    "rules": {
        "inline-if-style": "then",
        "block-if-style": "no-then",
        "condition-style": "no-group",
        "named-function-style": "auto",
        "anon-function-style": "auto",

        "type-annotations": "off",

        "assign-all-paths": "error",
        "unsafe-path-loop": "error",
        "unsafe-iterators": "error",
        "unreachable-code": "info",
        "case-sensitivity": "warn",
        "unused-variable": "warn",
        "consistent-return": "error"
    }
}

Code style rules

inline-if-style: validation of inline if/then statements.
- never: do not allow,
- no-then: do not use then keyword
- then: always use then keyword (default)
- off: do not validate
block-if-style: validation of regular block if/then statements.
- no-then: do not use then keyword (default)
- then: always use then keyword
- off: do not validate
condition-style: validation of if statements conditions: should the condition be wrapped around parenthesis?
- no-group: do not wrap with parenthesis (default)
- group: always wrap with parentheses
- off: do not validate
named-function-style, anon-function-style: validation of function style (function/sub)
- no-function: always use sub
- no-sub: always use function
- auto: use sub for Void functions, otherwise use function (default)
- off: no not validate

Strictness rules

type-annotations: validation of presence of as type annotations, for function arguments and return values.
- all: enforce both arguments and return type annotations
- return: enforce return type annotations
- args: engorce arguments type annotations
- off: do not validate (default)

Code flow rules

Valid values for the rules severity are: error | warn | info | off.

assign-all-paths: a variable is not assigned in all the possible code paths,
```
if a then
    b = "something"
end if
print b ' error
```

unsafe-path-loop: loops are considered as unsafe code paths: assignment in a loop may not happen.

for i = 0 to n
    b = "something"
end if
print b ' b may not have been assigned

unsafe-iterators: loop iterator variable should not be used outside a loop

for i = 0 to n
    b = "something"
end if
print i ' value could be invalid

case-sensitivity: inform of inconsistent variable casing
unused-variable: inform of variable being set but never used
unreachable-code: inform of unreachable code
```
return
print "is unreachable"
```
consistent-return: verifies consistency of sub/function returned values (missing return, missing value, returned value while function is as void,...)

slheavner / bslint