2017-10-26 17:47:42 +00:00
|
|
|
<p align="center">
|
2019-07-20 12:04:36 +00:00
|
|
|
<img src="https://raw.githubusercontent.com/veelenga/bin/master/ameba/logo.png" width="800">
|
2017-10-26 17:47:42 +00:00
|
|
|
<h3 align="center">Ameba</h3>
|
|
|
|
<p align="center">Code style linter for Crystal<p>
|
|
|
|
<p align="center">
|
|
|
|
<sup>
|
2017-11-16 09:42:14 +00:00
|
|
|
<i> (a single-celled animal that catches food and moves about by extending fingerlike projections of protoplasm) </i>
|
2017-10-26 17:47:42 +00:00
|
|
|
</sup>
|
|
|
|
</p>
|
2017-10-30 20:10:03 +00:00
|
|
|
<p align="center">
|
2017-11-03 10:12:45 +00:00
|
|
|
<a href="https://travis-ci.org/veelenga/ameba"><img src="https://travis-ci.org/veelenga/ameba.svg?branch=master"></a>
|
2019-07-20 12:18:35 +00:00
|
|
|
<a href="https://github.com/crystal-ameba/ameba/releases"><img src="https://img.shields.io/github/release/crystal-ameba/ameba.svg?maxAge=360"></a>
|
|
|
|
<a href="https://github.com/crystal-ameba/ameba/blob/master/LICENSE"><img src="https://img.shields.io/github/license/crystal-ameba/ameba.svg"></a>
|
2017-11-02 08:39:29 +00:00
|
|
|
<a href="https://gitter.im/veelenga/ameba?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge"><img src="https://badges.gitter.im/veelenga/ameba.svg"></a>
|
2017-10-30 20:10:03 +00:00
|
|
|
</p>
|
2017-10-26 17:47:42 +00:00
|
|
|
</p>
|
|
|
|
|
2017-11-01 17:14:38 +00:00
|
|
|
## About
|
2017-10-26 17:47:42 +00:00
|
|
|
|
2017-11-17 18:28:45 +00:00
|
|
|
Ameba is a static code analysis tool for the Crystal language.
|
|
|
|
It enforces a consistent [Crystal code style](https://crystal-lang.org/docs/conventions/coding_style.html),
|
|
|
|
also catches code smells and wrong code constructions.
|
|
|
|
|
2019-07-20 12:18:35 +00:00
|
|
|
See also [Roadmap](https://github.com/crystal-ameba/ameba/wiki).
|
2018-05-13 19:00:08 +00:00
|
|
|
|
2018-05-08 21:28:06 +00:00
|
|
|
## Usage
|
|
|
|
|
|
|
|
Run `ameba` binary within your project directory to catch code issues:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ ameba
|
|
|
|
Inspecting 107 files.
|
|
|
|
|
2018-05-14 13:28:46 +00:00
|
|
|
...............F.....................F....................................................................
|
2018-05-08 21:28:06 +00:00
|
|
|
|
2018-12-12 19:45:00 +00:00
|
|
|
src/ameba/formatter/flycheck_formatter.cr:4:33
|
2019-04-14 16:37:03 +00:00
|
|
|
[W] Lint/UnusedArgument: Unused argument `location`
|
2018-12-12 19:45:00 +00:00
|
|
|
> source.issues.each do |e, location|
|
|
|
|
^
|
|
|
|
|
|
|
|
src/ameba/formatter/base_formatter.cr:12:7
|
2019-04-14 16:37:03 +00:00
|
|
|
[W] Lint/UselessAssign: Useless assignment to variable `s`
|
2018-12-12 19:45:00 +00:00
|
|
|
> return s += issues.size
|
|
|
|
^
|
2017-11-17 18:28:45 +00:00
|
|
|
|
2018-12-12 19:45:00 +00:00
|
|
|
Finished in 542.64 milliseconds
|
2017-11-17 18:28:45 +00:00
|
|
|
|
2018-12-12 19:45:00 +00:00
|
|
|
129 inspected, 2 failures.
|
2018-05-08 21:28:06 +00:00
|
|
|
|
|
|
|
```
|
2017-11-01 17:14:38 +00:00
|
|
|
|
2017-10-26 16:46:58 +00:00
|
|
|
## Installation
|
|
|
|
|
2017-11-14 18:52:15 +00:00
|
|
|
### As a project dependency:
|
|
|
|
|
2017-10-26 16:46:58 +00:00
|
|
|
Add this to your application's `shard.yml`:
|
|
|
|
|
|
|
|
```yaml
|
2017-10-26 17:47:42 +00:00
|
|
|
development_dependencies:
|
2017-10-26 16:46:58 +00:00
|
|
|
ameba:
|
2019-07-20 12:18:35 +00:00
|
|
|
github: crystal-ameba/ameba
|
2019-06-06 16:11:23 +00:00
|
|
|
version: ~> 0.10.0
|
2017-10-26 16:46:58 +00:00
|
|
|
```
|
|
|
|
|
2018-04-11 09:38:36 +00:00
|
|
|
Build `bin/ameba` binary within your project directory while running `shards install`.
|
2017-11-16 08:18:11 +00:00
|
|
|
|
2017-11-17 18:28:45 +00:00
|
|
|
You may also want to use it on [Travis](travis-ci.org):
|
2017-11-16 08:18:11 +00:00
|
|
|
|
|
|
|
```yaml
|
2017-11-17 18:28:45 +00:00
|
|
|
# .travis.yml
|
2017-11-16 08:18:11 +00:00
|
|
|
language: crystal
|
|
|
|
install:
|
2018-04-11 09:38:36 +00:00
|
|
|
- shards install
|
2017-11-16 08:18:11 +00:00
|
|
|
script:
|
|
|
|
- crystal spec
|
2019-07-18 10:53:04 +00:00
|
|
|
- crystal bin/ameba.cr
|
2017-11-16 08:18:11 +00:00
|
|
|
```
|
2017-11-14 18:52:15 +00:00
|
|
|
|
2017-11-17 18:58:52 +00:00
|
|
|
Using this config Ameba will inspect files just after the specs run. Travis will also fail
|
2017-11-17 18:28:45 +00:00
|
|
|
the build if some problems detected.
|
|
|
|
|
2017-11-14 18:52:15 +00:00
|
|
|
### OS X
|
|
|
|
|
2017-11-14 23:02:07 +00:00
|
|
|
```sh
|
2017-11-14 18:52:15 +00:00
|
|
|
$ brew tap veelenga/tap
|
|
|
|
$ brew install ameba
|
|
|
|
```
|
|
|
|
|
2018-08-25 10:55:07 +00:00
|
|
|
### Docker
|
|
|
|
|
|
|
|
Build the image:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ docker build -t ameba/ameba .
|
|
|
|
```
|
|
|
|
|
|
|
|
To use the resulting image on a local source folder, mount the current (or target) directory into `/src`:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ docker run -v $(pwd):/src ameba/ameba
|
|
|
|
```
|
|
|
|
|
2017-11-14 18:52:15 +00:00
|
|
|
### From sources
|
2017-10-26 16:46:58 +00:00
|
|
|
|
2017-11-14 23:02:07 +00:00
|
|
|
```sh
|
2019-07-20 12:18:35 +00:00
|
|
|
$ git clone https://github.com/crystal-ameba/ameba && cd ameba
|
2017-11-14 18:52:15 +00:00
|
|
|
$ make install
|
|
|
|
```
|
2017-10-26 16:46:58 +00:00
|
|
|
|
2017-11-14 07:24:36 +00:00
|
|
|
## Configuration
|
|
|
|
|
2017-11-17 18:28:45 +00:00
|
|
|
Default configuration file is `.ameba.yml`.
|
2017-12-01 17:00:11 +00:00
|
|
|
It allows to configure rule properties, disable specific rules and exclude sources from the rules.
|
|
|
|
|
|
|
|
Generate new file by running `ameba --gen-config`.
|
2017-11-14 07:24:36 +00:00
|
|
|
|
2018-06-18 07:25:06 +00:00
|
|
|
### Only/Except
|
|
|
|
|
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2018-12-27 21:34:10 +00:00
|
|
|
### Explanation
|
|
|
|
|
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2018-01-29 22:25:36 +00:00
|
|
|
### Inline disabling
|
|
|
|
|
2018-06-23 13:52:48 +00:00
|
|
|
One or more rules or one or more group of rules can be disabled using inline directives:
|
2018-01-29 22:25:36 +00:00
|
|
|
|
|
|
|
```crystal
|
2018-06-16 11:50:59 +00:00
|
|
|
# ameba:disable Style/LargeNumbers
|
2018-01-29 22:25:36 +00:00
|
|
|
time = Time.epoch(1483859302)
|
|
|
|
|
2018-06-23 13:52:48 +00:00
|
|
|
time = Time.epoch(1483859302) # ameba:disable Style/LargeNumbers, Lint/UselessAssign
|
|
|
|
|
|
|
|
time = Time.epoch(1483859302) # ameba:disable Style, Lint
|
2018-01-29 22:25:36 +00:00
|
|
|
```
|
|
|
|
|
2018-01-24 13:23:00 +00:00
|
|
|
## Editor integration
|
|
|
|
|
2019-01-29 10:52:31 +00:00
|
|
|
* Vim: [vim-crystal](https://github.com/rhysd/vim-crystal), [Ale](https://github.com/w0rp/ale)
|
2019-07-20 12:18:35 +00:00
|
|
|
* Emacs: [ameba.el](https://github.com/crystal-ameba/ameba.el)
|
2018-05-12 18:20:05 +00:00
|
|
|
* Sublime Text: [Sublime Linter Ameba](https://github.com/epergo/SublimeLinter-contrib-ameba)
|
2019-07-20 12:18:35 +00:00
|
|
|
* VSCode: [vscode-crystal-ameba](https://github.com/crystal-ameba/vscode-crystal-ameba)
|
2018-01-24 13:23:00 +00:00
|
|
|
|
2017-11-17 18:28:45 +00:00
|
|
|
## Credits & inspirations
|
|
|
|
|
|
|
|
- [Crystal Language](crystal-lang.org)
|
|
|
|
- [Rubocop](http://rubocop.readthedocs.io/en/latest/)
|
|
|
|
- [Credo](http://credo-ci.org/)
|
|
|
|
- [Dogma](https://github.com/lpil/dogma)
|
|
|
|
|
2017-10-26 16:46:58 +00:00
|
|
|
## Contributors
|
|
|
|
|
2017-10-26 17:47:42 +00:00
|
|
|
- [veelenga](https://github.com/veelenga) Vitalii Elenhaupt - creator, maintainer
|