pulsar-shellcheck

Lints shell scripts in Pulsar by running the ShellCheck binary, and lets you switch any of its 519 rules on or off from a searchable list.

What you need

ShellCheck itself. The package does not bundle it.

sudo apt install shellcheck     # Debian, Ubuntu
sudo dnf install ShellCheck     # Fedora
brew install shellcheck         # macOS

The linter and linter-ui-default packages draw the results. They install themselves the first time this package runs.

What it does

• Underlines problems in the editor, with the rule code and a link to its wiki page.
• Applies ShellCheck's own fixes. ShellCheck works out the correction; this turns it into a one-click quick fix.
• Lints the whole project, including files you do not have open.
• Gives every rule its own toggle in a searchable browser, rather than asking you to remember codes and type them into a box.

Settings

Most of it lives in Settings → Packages → pulsar-shellcheck.

Setting	What it does
ShellCheck Executable Path	Where the binary is. shellcheck finds it on your PATH.
When To Lint	On save, as you type, or only when you ask.
Minimum Severity To Report	Anything below this is never reported.
Shell Assumed When There Is No Shebang	What to check against for a file with no #! line.
Disabled Rules	Codes to ignore. Easier to set from the rule browser.
Enabled Optional Rules	ShellCheck's nine optional checks, which are off by default.
Follow Sourced Files	Lets ShellCheck read the files you source.
Source Search Paths	Where to look for them. SCRIPTDIR means the script's own folder.
Timeout	Gives up on a run that hangs.

The rule browser

The settings page cannot hold a 519-row list — Pulsar builds that page from a fixed schema and offers no way in. So the rules live in their own tab.

Open it from the link in the Disabled Rules description, from Packages → ShellCheck → Browse Rules…, or from the command palette with ShellCheck: Open Rule Browser.

Each row is a rule. The checkbox means is this rule active, which is not the same as is a flag set: most rules are on until you exclude them, while the nine optional checks are off until you enable them. The browser handles that difference so you do not have to.

Some rows are greyed out, and the reason is written under them:

• Removed from ShellCheck or added after 0.10.0 — your binary cannot emit it.
• POSIX portability rules (SC3xxx) — these only fire when the target shell is sh, dash or busybox. Under bash, no toggle changes them.
• Pinned by a .shellcheckrc — see below.

About .shellcheckrc

If your project has one, it wins. A rule that a .shellcheckrc turns off cannot be turned back on from the editor — that is ShellCheck's own behaviour, not a limitation here. So instead of showing you a checkbox that would quietly do nothing, the browser shows a banner naming the file in charge and greys those rows out.

The package reads an existing .shellcheckrc. It will never write one.

Commands

Command	Default key
ShellCheck: Lint	ctrl-alt-s in a shell script
ShellCheck: Lint Project	—
ShellCheck: Clear	—
ShellCheck: Open Rule Browser	—

Notes on how it behaves

Files it will not touch. Pulsar's shell grammar also claims zsh, tcsh and even npmrc. ShellCheck 0.10.0 understands only sh, bash, dash, ksh and busybox, so anything else is skipped rather than checked against the wrong language.

It will not lint your Makefile. The linter package picks linters by the syntax under your cursor, and shell syntax is embedded in Makefile recipes, Markdown ```bash blocks and Ruby heredocs. This package checks the file's own grammar before running.

A typo in a rule code is reported. Give ShellCheck a code it cannot parse and it exits with no output at all, which looks exactly like the linter being broken. Codes are checked before anything runs, and a bad one gets a notification.

Development

git clone git@github.com:vaiolabs-io/pulsar-shellcheck.git
cd pulsar-shellcheck
ppm install
ppm link --dev
pulsar --dev .
ppm test

License

MIT. See LICENSE.md.