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.
Run ameba binary within your project directory to catch code issues:
$ ameba
Inspecting 107 files
...............F.....................FF....................................................................
src/ameba/formatter/flycheck_formatter.cr:6:37
[W] Lint/UnusedArgument: Unused argument `location`. If it's necessary, use `_` as an argument name to indicate that it won't be used.
> source.issues.each do |issue, location|
^
src/ameba/formatter/base_formatter.cr:16:14
[W] Lint/UselessAssign: Useless assignment to variable `s`
> return s += issues.size
^
src/ameba/formatter/base_formatter.cr:16:7 [Correctable]
[C] Style/RedundantReturn: Redundant `return` detected
> return s += issues.size
^---------------------^
Finished in 389.45 milliseconds
107 inspected, 3 failures
🎬 Watch the LuckyCast showing how to use Ameba
Rules that are marked as [Correctable] in the output can be automatically corrected using --fix flag:
$ ameba --fixAmeba 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 thingSome 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 secondsAdd this to your application's shard.yml:
development_dependencies:
ameba:
github: crystal-ameba/amebaBuild bin/ameba binary within your project directory while running shards install.
$ brew tap crystal-ameba/ameba
$ brew install amebaBuild the image:
$ docker build -t ghcr.io/crystal-ameba/ameba .To use the resulting image on a local source folder, mount the current (or target) directory into /src:
$ docker run -v $(pwd):/src ghcr.io/crystal-ameba/amebaAlso available on GitHub: https://github.com/crystal-ameba/ameba/pkgs/container/ameba
$ git clone https://github.com/crystal-ameba/ameba && cd ameba
$ make installDefault configuration file is .ameba.yml.
It allows to configure rule properties, disable specific rules and exclude sources from the rules.
Generate new file by running ameba --gen-config.
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 **/*.ecr], meaning it includes all project files with*.crand*.ecrextensions.Excludedsection - an array of wildcards (or paths) to exclude from the source list defined byGlobs. Defaults to%w[lib], meaning it excludes thelibfolder.
In this example we define default globs and exclude lib and src/compiler folders:
Globs:
- "**/*.cr"
- "**/*.ecr"
Excluded:
- lib
- src/compilerSpecific sources can be excluded at rule level:
Style/RedundantBegin:
Excluded:
- src/server/processor.cr
- src/server/api.crOne 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 groupsOr through the configuration file:
Style/RedundantBegin:
Enabled: falseOne 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- Vim: vim-crystal, Ale
- Emacs: ameba.el
- Sublime Text: Sublime Linter Ameba
- VSCode: vscode-crystal-ameba
- Codacy: codacy-ameba
- GitHub Actions: github-action