angler

A pluggable linter for Carp source. Built on carpentry-org/carp-reader and carpentry-org/parsec.

Most users invoke angler as a CLI (angler FILE…). The library surface is documented here for plugin authors and programmatic consumers. See the documentation on writing rules.

(load "git@github.com:carpentry-org/angler@0.5.1")

(match (Lint.lint-source "(do x)")
  (Result.Success diags) (for [i 0 (Array.length &diags)]
                           (IO.println &(Diagnostic.str (Array.unsafe-nth &diags i))))
  (Result.Error e)       (IO.errorln &(Parser.format-error &e)))

Modules

• Lint, the rule registry, walker, and public entry points (lint, lint-with, lint-source, lint-source-with, register-rule!, register-file-rule!, list-rules).
• Diagnostic, one finding's data and renderer (line:col: [rule] message).
• Rule, the registry entry: name, description, and matcher function.

Built-in rules

• lonely-do, on (do x).
• empty-do, on (do).
• if-with-do, on (if c (do …) ()) and (if c () (do …)).
• if-one-branch-empty, on (if c x ()) and (if c () x) (non-do bodies).
• form-with-do, on (let / while / when / unless ... (do …)).
• when-with-not, on (when (not c) x) and (unless (not c) x).
• not-equal, on (not (= a b)).
• double-not, on (not (not x)).
• set-self, on (set! x x).
• try-around-atomic, on (Parser.try (Parser.string/byte …)).
• non-kebab-case-defn, on (defn FooBar …).
• non-pascal-case-defmodule, on (defmodule my-thing …).

CLI

• angler FILE [FILE…], lints every file with every registered rule.
• --only RULES, comma-separated allow-list.
• --disable RULES, comma-separated deny-list.
• --list-rules, prints the registry and exits.
• -h, --help, prints usage.

Suppressing findings

A ; angler-disable-next-line, ; angler-disable-line or ; angler-disable-file comment in the linted file switches rules off for the line below it, its own line, or the whole file. Each takes a space- or comma-separated list of rule names; none means every rule. Suppression applies to --fix as well as to reporting.