linters

Adds checks that run when a macro is saved and report warnings or errors about it.

Details #

A linter reads a macro and says what looks wrong with it. The linters point adds a check that runs when a macro is saved. What it finds shows up as the warning dot in the editor, with your message, prefixed with the extension's name.

Use it for house rules: every macro needs a name, no step may type a password, no macro may have more than 30 steps.

Declare it in switchboard.json under adds.linters:

{
  "adds": {
    "linters": [
      { "id": "tidy", "title": "Tidy macros" }
    ]
  }
}

And implement it:

import { defineExtension, linter } from '@switchboard/sdk';

export default defineExtension({
  linters: [
    linter('tidy', ({ macro }) =>
      macro.name ? [] : [{ severity: 'warning', path: '$.name', message: 'Give this macro a name.' }]),
  ],
});

Gotchas #

The handler must answer within 5 seconds, or its findings are skipped for that save.
A linter that throws is skipped and the macro still saves. A linter never blocks a save.
It reads only the macro. For checks that need the network or files, do the work somewhere else and keep the linter quick.
Unknown keys in an entry are refused.

A complete extension using this point can be downloaded from the Full example section and edited: three house rules that run on save.

Manifest fields #

Field	Required	What it is
`id`	yes	Lowercase letters, digits and `.` `_` `-`, up to 64 characters, starting with a letter. Unique in the list.
`title`	yes	1 to 80 characters.
`description`	no	Up to 1000 characters.
`appliesTo`	no	1 to 200 characters. Accepted in the manifest, but the engine does not use it yet: it runs every enabled linter on every macro. Check the macro in your handler for anything you only want on some of them.

What the handler gets and returns #

The handler gets { macro }, the whole macro as saved (id, name, enabled, when, onlyIf, do, and the rest).

It returns a list of findings. An empty list means all is well. A finding has:

message: what is wrong, in a sentence a person can act on. Required; a finding without one is dropped.
severity: warning (the default) or error.
path: where in the macro, like $.name or $.do[3]. The default is $, the macro as a whole.