Carve

Carve out the essentials of your Clojure app.

Rationale

Carve will search through your code for unused vars and will remove them.

Status

Experimental. Use with caution! Breaking changes may happen. Feedback and bugfix PRs welcome.

Installation

CLI

Brew (linux and macOS)

 brew install borkdude/brew/carve

Arch (Linux)

carve

yay

yay -S carve-bin

Manual

Grab the binary for your OS at Github releases.

JVM

Add to your

deps.edn

:aliases

:carve {:extra-deps {borkdude/carve {:git/url "https://github.com/borkdude/carve"
                                     :sha ""}}
        :main-opts ["-m" "carve.main"]}

where the latest SHA can be found with:

$ git ls-remote https://github.com/borkdude/carve.git refs/heads/master

How does it work?

Carve invokes clj-kondo and uses the analysis information to check which vars are unused. To remove the relevant bits of code it uses rewrite-cljc.

Usage

The usage for a typical Clojure app looks like:

carve --opts '{:paths ["src" "test"]}'

for the CLI or:

clojure -M:carve --opts '{:paths ["src" "test"]}'

on the JVM.

You can also store the config for your project in

.carve/config.edn

.carve/config.edn

.carve/config.edn

Currently

carve

--opts

:paths

• :paths

  : a list of paths to analyze. Can be a mix of individual files and directories.

• :ignore-vars

  : a list of vars to ignore. Useful for when the analyzer has it wrong or you just want to keep the var for whatever reason.

• :api-namespaces

  : a list of namespaces of which only unused private vars will be reported.

• :carve-ignore-file

  : a file where ignored vars can be stored,

  .carve/ignore

  by default.

• :interactive

  : ask what to do with an unused var: remove from the file, add to

  .carve/ignore

  or continue. Set to

  true

  by default.

• :out-dir

  : instead of writing back to the original file, write to this dir.

• :dry-run

  : just print the unused var expression.

• :aggressive

  : runs multiple times until no unused vars are left. Defaults to

  false

  .

• :report

  : when truthy, prints unused vars to stdout. Implies

  :dry-run
  true

  . The output format may be set using

  :report {:format ...}

  where format can be

  :edn

  ,

  :text

  or

  :ignore

  . The text output can be interpreted by editors like Emacs. This option can be combined with

  :aggressive

  .

• :silent

  : when truthy, does not write to stdout. Implies

  :interactive false

  .

• :clj-kondo/config

  : a map of clj-kondo config opts that are passed on to clj-kondo, which is used to analyze usages. e.g.: passing

  {:skip-comments
  true}

  will ignore function usage in

  (comment)

  forms. Note that the config in

  .clj-kondo/config.edn

  is used as well - options passed with this key will override options set in the clj-kondo config file.

$ clojure -M:carve --opts '{:paths ["test-resources"] :dry-run true}'
Carving test-resources/app.clj

Found unused var:
(defn unused-function [])
...
Carving test-resources/api.clj
Found unused var:
(defn- private-lib-function [])
...

$ clojure -M:carve --opts '{:paths ["test-resources"]}'
Carving test-resources/app.clj

Found unused var:
(defn unused-function [])
Type Y to remove or i to add app/unused-function to .carve/ignore
n
Found unused var:
(defn another-unused-function [])
Type Y to remove or i to add app/another-unused-function to .carve/ignore
i
...
$ cat .carve/ignore
app/another-unused-function

Keep in mind that if you ran

carve

'{:paths ["src" "test"]}'

So after a first cycle of carving you might want to do another run with simply

{:paths ["src"]}

Carve also removes any unused refers from namespace

:require

CI integration

A good use case for Carve is the CI integration, to ensure that no one can introduce dead code into a codebase. This example shows how to add this step into CircleCI, but any other CI configuration will be similar.

First add this configuration into a

.circleci/deps.edn

{:aliases
 {:carve {:extra-deps {borkdude/carve {:git/url "https://github.com/borkdude/carve"
                                       :sha "$LATEST_CARVE_SHA"}}
          :main-opts ["-m" "carve.main"]}}}

Then configure your build step like this:

find_dead_code:
  working_directory: ~/$your-project
  docker:
    - image: circleci/clojure:openjdk-11-tools-deps

  steps:
    - checkout
    - run: mkdir -p ~/.clojure && cp .circleci/deps.edn ~/.clojure/deps.edn
    - run: clojure -M:carve --opts '{:paths ["src" "test"] :report {:format :text}}'

If the

report

1

Emacs

Report mode

Running carve with in report mode (for example

clojure -M:carve --opts '{:paths
["src" "test"] :report {:format :text}}'

Using

:report {:format :ignore}

carve --opts '{:paths ["src" "test"] :report {:format :ignore}}' > .carve/ignore

Articles

• Carve that Clojure codebase by Andrea Crotti

Dev

Running tests

If you want to run tests in Emacs and Cider you need to use the test alias, or it will fail while trying to load the

test.check

.dir-locals.el

((clojure-mode . ((cider-clojure-cli-global-options . "-R:test"))))

or alter the command used by

cider-jack-in

C-u

License

Copyright © 2019-2021 Michiel Borkent

Distributed under the EPL License. See LICENSE.