Add the following code to your project's shard.yml under:
to use in production
- OR -
development_dependencies to use in development
Code style linter for Crystal
(a single-celled animal that catches food and moves about by extending fingerlike projections of protoplasm)
Ameba is a static code analysis tool for the Crystal language. It enforces a consistent Crystal code style, also catches code smells and wrong code constructions.
See also Roadmap.
ameba binary within your project directory to catch code issues:
$ ameba Inspecting 107 files. ...............F.....................F.................................................................... src/ameba/formatter/flycheck_formatter.cr:4:33 [W] Lint/UnusedArgument: Unused argument `location` > source.issues.each do |e, location| ^ src/ameba/formatter/base_formatter.cr:12:7 [W] Lint/UselessAssign: Useless assignment to variable `s` > return s += issues.size ^ Finished in 542.64 milliseconds 129 inspected, 2 failures.
Starting from 0.31.0 Crystal supports parallelism. It allows to run linting in parallel too. In order to take advantage of this feature you need to build ameba with preview_mt support:
$ crystal build src/cli.cr -Dpreview_mt -o bin/ameba $ make install
Some quick benchmark results measured while running Ameba on Crystal repo:
$ CRYSTAL_WORKERS=1 ameba #=> 29.11 seconds $ CRYSTAL_WORKERS=2 ameba #=> 19.49 seconds $ CRYSTAL_WORKERS=4 ameba #=> 13.48 seconds $ CRYSTAL_WORKERS=8 ameba #=> 10.14 seconds
Add this to your application's
development_dependencies: ameba: github: crystal-ameba/ameba version: ~> 0.12.0
bin/ameba binary within your project directory while running
You may also want to use it on Travis:
# .travis.yml language: crystal install: - shards install script: - crystal spec - crystal bin/ameba.cr
Using this config Ameba will inspect files just after the specs run. Travis will also fail the build if some problems detected.
$ brew tap veelenga/tap $ brew install ameba
Build the image:
$ docker build -t ameba/ameba .
To use the resulting image on a local source folder, mount the current (or target) directory into
$ docker run -v $(pwd):/src ameba/ameba
$ git clone https://github.com/crystal-ameba/ameba && cd ameba $ make install
Default configuration file is
It allows to configure rule properties, disable specific rules and exclude sources from the rules.
Generate new file by running
List of sources to run Ameba on can be configured globally via:
Globssection - an array of wildcards (or paths) to include to the inspection. Defaults to
%w(**/*.cr !lib), meaning it includes all project files with
*.crextension except those which exist in
Excludedsection - an array of wildcards (or paths) to exclude from the source list defined by
Globs. Defaults to an empty array.
In this example we define default globs and exclude
Globs: - **/*.cr - !lib Excluded: - src/compiler
Specific sources can be excluded at rule level:
Style/RedundantBegin: Excluded: - src/server/processor.cr - src/server/api.cr
One or more rules, or a one or more group of rules can be included or excluded via command line arguments:
$ ameba --only Lint/Syntax # runs only Lint/Syntax rule $ ameba --only Style,Lint # runs only rules from Style and Lint groups $ ameba --except Lint/Syntax # runs all rules except Lint/Syntax $ ameba --except Style,Lint # runs all rules except rules in Style and Lint groups
Or through the configuration file:
Style/RedundantBegin: Enabled: false
Ameba allows you to dig deeper into an issue, by showing you details about the issue and the reasoning by it being reported.
To be convenient, you can just copy-paste the
PATH:line:column string from the
report and paste behind the
ameba command to check it out.
$ ameba crystal/command/format.cr:26:83 # show explanation for the issue $ ameba --explain crystal/command/format.cr:26:83 # same thing
One or more rules or one or more group of rules can be disabled using inline directives:
# ameba:disable Style/LargeNumbers time = Time.epoch(1483859302) time = Time.epoch(1483859302) # ameba:disable Style/LargeNumbers, Lint/UselessAssign time = Time.epoch(1483859302) # ameba:disable Style, Lint