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",
        "no-print": "off",

        "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

• no-print: prevent usage of print statements in code (error | warn | info | off)

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,...)