clj-kondo / clj-kondo

A static analyzer and linter for Clojure code that sparks joy. Thanks a lot for clj-kondo. It is like a companion for me. It has made clojure fun again. — @geraldodev on Clojurians Slack Rationale Clj-kondo performs [static analysis]() on Clojure, ClojureScript and EDN. It informs you about potential errors while you are typing (without executing your program). Features Clj-kondo detects: • inline expressions • redundant and wrappings • arity errors: • within the same namespace and across namespaces • of static Java method calls • of local and binding calls • of recursive calls (including ) • conflicting arities in overloaded functions • unused private vars • private and deprecated var usage • required but unused namespaces • unsorted required namespaces • referred but unused vars • duplicate requires • unused function arguments and let bindings • marked as unused, but used arguments and let bindings (optional) • unused imports • redefined vars • unresolved symbols, vars and namespaces • misplaced docstrings • duplicate map keys and set elements • duplicates and quoting in case test constants • missing map keys • invalid number of forms in binding vectors • missing assertions in • alias consistency • type checking • Datalog syntax checking • format string argument mismatches • shadowed vars • 2 argument usage of reduce (optional) before your form hits the REPL. It suggests several style guide recommendations, such as: • rules from Stuart Sierra's how to ns • use as the catch-all test expression in (see Clojure style guide) • use instead of (see Clojure style guide) • don't make your lines too long (see Clojure style guide) It has support for syntax of commonly used macros like , and . It detects common errors in and It provides analysis data so you build your own custom linters. View all available linters here. This linter is: • compatible with , , and files • build tool and editor agnostic • a static code analyzer • compiled to native code using GraalVM Try clj-kondo at the interactive playground. Watch the talk: Support :heart: You can support this project via Github Sponsors, OpenCollective, Ko-fi or indirectly via Clojurists Together. Top sponsors • Clojurists Together • Roam Research • Nextjournal • Toyokumo • Cognitect • Kepler16 • Adgoji Installation Running on the JVM Running with Docker Usage Command line Lint from stdin: Lint a file: Lint a directory: Lint a project classpath: Help: Project setup To detect lint errors across namespaces in your project, a cache is needed. To let clj-kondo know where to create one, make a directory in the root of your project, meaning on the same level as your , or : A cache will be created inside of it when you run . Before linting inside your editor, it is recommended to lint the entire classpath to teach about all the libraries you are using, including Clojure and/or ClojureScript itself. Some libraries come with configurations. To import them, first run: The flag will search and copy configurations from dependencies into the directory, while linting (see config.md). With the configurations in place, now we can analyze the dependencies properly: The flag indicates that clj-kondo is used to analyze sources to populate the cache. When enabled, clj-kondo will suppress warnings and skips over already linted files for performance. The option will use multiple threads to lint your sources, going through them faster. NOTE: in the version after copying configs and linting dependencies can be done in one go using: Build tool specific ways to get a classpath: • • • • So for the entire command would be: $ clj-kondo --lint "$(lein classpath)" --dependencies --parallel --copy-configs Now you are ready to lint single files using editor integration. A simulation of what happens when you edit a file in your editor: Since clj-kondo now knows about your version of ClojureScript via the cache, it detects that the number of arguments you passed to is invalid. Each time you edit a file, the cache is incrementally updated, so clj-kondo is informed about new functions you just wrote. If you want to use a different directory to read and write the cache, use the option. To disable the cache even if you have a directory, use . For your project's version control, we recommend that you commit everything under the dir, except for the cache dir. Add to your to ignore all dirs, including the one under . Adjust accordingly if you are using a different . Configuration Editor integration Exit codes Exit codes can be controlled by the option. The default fail level is which returns exit codes as follows: • : no errors or warnings were found • : one or more warnings were found • : one or more errors were found If is supplied, warnings do not lead to a non-zero exit code: • : no errors were found • : one or more warnings were found • : one or more errors were found All exit codes other than , and indicate an error because of a bug in clj-kondo or some other unexpected error beyond the control of clj-kondo. CI Integration Analysis data Developer documentation Companies using clj-kondo Macros As clj-kondo is a static analyzer is does not need a runtime (JVM, browser, Node.js, etc.). It doesn't execute your code. As such it can be a faster alternative to linters that do use a runtime, like eastwood. This approach comes with the limitation that clj-kondo cannot execute your macros as macros can use arbitrary features from a runtime. Clj-kondo has support for clojure core macros and some popular libraries from the community. Macros that are not supported out of the box can be supported using configuration. One of the ways to configure macros is to write hooks for them (also see this blogpost). For many libraries there is already a configuration available that you can import. Also check out clj-kondo configs which contains configurations for third party libraries. Babashka pod Clj-kondo can be invoked as a babashka…