Eastwood Clojure Linter

The :reflection linter helps you identify and address reflection warnings from the Clojure compiler. Addressing these improves performance, maintainability, and compatibility with newer JDKs and GraalVM.

Key Behaviors:

• Scope: By default, it only emits warnings if reflection occurs within your project's source or test paths.
• Overrides: It ignores any (set! warn-on-reflection ...) settings in a namespace, as Eastwood analyzes each top-level form with a binding that overrides the surrounding choice.
• Macros: If a third-party macro expands to reflective access within your source path, it will be reported, as this creates reflective code in your codebase.

Accuracy and Requirements

Eastwood uses tools.analyzer and prefers evaluation and macroexpansion over other approaches to ensure high accuracy (comparable to the Clojure compiler).

Critical Requirement: Eastwood can only lint a file if Clojure can successfully compile it. If a file has syntax errors, Eastwood will not be able to finish linting it. It is recommended to run lein test or lein check before running Eastwood to ensure your code is compilable.

Supported Runtimes

• Supported: JVM Clojure (>= 1.7.0).
• Not Supported: ClojureScript or Clojure/CLR. For ClojureScript support, consider using .cljc files.

The :wrong-pre-post linter ensures that Clojure preconditions (:pre) and postconditions (:post) are defined correctly.

Common mistakes detected:

• Missing vectors: Pre/postconditions must be a vector of expressions. If you provide a single expression instead of a vector (e.g., {:pre (>= x 0)} instead of {:pre [(>= x 0)]}), Clojure treats the expression as multiple independent assertions, which often results in no errors being thrown.
• Always-true conditions: The linter checks if any conditions in the vector are values that are always logically true or false (e.g., passing a function Var like non-neg? instead of a call like [non-neg? x]).

The extend-type and extend-protocol macros propagate the provided class name as a type tag to the first argument of all functions. If you use a runtime-evaluated expression (like (Class/forName "[D")) as the type, the macro expands to an invalid type tag that Clojure silently ignores, causing reflection. Eastwood will issue a :wrong-tag warning.

Solution: Use the extend function instead of the convenience macros. This allows you to use a valid type tag (like ^doubles) on the first argument manually, which avoids reflection and satisfies Eastwood.

;; Avoid this (causes :wrong-tag and reflection):
(extend-protocol PGetElem
  (Class/forName "[D")
    (get-elem [m idx] (aget m idx)))

;; Use this instead (avoids reflection and warnings):
(extend (Class/forName "[D")
 PGetElem
 {:get-elem
  (fn ([^doubles m idx]
    (aget m idx)))})

The :non-dynamic-earmuffs linter enforces a naming convention for dynamic variables. Variables marked ^:dynamic should use 'earmuff' notation (surrounded by asterisks), and non-dynamic variables should not.

Valid Examples:

• (def foo 42) (Non-dynamic, no earmuffs)
• (def ^:dynamic *foo* 42) (Dynamic, with earmuffs)

Invalid Examples:

• (def ^:dynamic foo 42) (Dynamic, but missing earmuffs)
• (def *foo* 42) (Earmuffed, but missing ^:dynamic tag)

Eastwood performs a mandatory check to ensure that Clojure file names match their declared namespaces. This check is performed before any other linting.

Rules:

• Dots in a namespace (e.g., foo.bar.baz) must correspond to path separators (foo/bar/baz.clj).
• Dashes in a namespace (e.g., foo.bar.baz-tests) must correspond to underscores in the file name (foo/bar/baz_tests.clj).

If a mismatch is found in files within :source-paths or :test-paths, Eastwood will print an error and abort all further linting. This prevents issues where require fails or tests are skipped due to incorrect file/namespace mapping.

The :unused-meta-on-macro linter warns when metadata (like type hints) is applied to a macro invocation that will be discarded by Clojure upon expansion. This often leads to confusing reflection warnings from the Clojure compiler.

Common scenarios where metadata is lost:

• Constructor calls: (ClassName. args)
• Most other macro expansions.

Scenarios where metadata is preserved:

• (new ClassName args)
• Calls beginning with a . (e.g., (. x close))
• Class method calls, field access, and instance method/field access (these preserve :tag type hints).

Workaround: To avoid reflection without triggering the linter, bind the macro invocation result to a symbol using let and type hint that symbol instead.

;; Instead of: (.close ^Writer (my-macro (StringWriter.)))
;; Use:
(let [^Writer w (my-macro (StringWriter.))]
  (.close w))

The :unlimited-use linter warns against using use for namespaces like clojure.string because it can lead to symbol shadowing and makes it difficult to track the origin of symbols.

Best Practices:

• Use require with :refer to explicitly list symbols.
• Use :as to create an alias (e.g., :as str) to prefix symbols.

Exceptions:

• The linter ignores 'limited' use statements that use :only or :refer.
• The linter never warns about clojure.test in test files, as unlimited use is common and generally considered harmless there.

(ns my.namespace
  (:require [clojure.string :as str :refer [replace join]]))

The :constant-test linter warns when a test condition is a compile-time constant that will always evaluate to true or false.

Examples of flagged code:

(if false 1 2)
(if-not [nil] 1 2)
(when-first [x [1 2]] (println "Goodbye"))