shard-ameba/README.md

172 lines
4.9 KiB
Markdown
Raw Normal View History

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">
2019-07-20 12:26:48 +00:00
<a href="https://travis-ci.org/crystal-ameba/ameba"><img src="https://travis-ci.org/crystal-ameba/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>
## 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
## Usage
Run `ameba` binary within your project directory to catch code issues:
```sh
$ ameba
Inspecting 107 files.
...............F.....................F....................................................................
src/ameba/formatter/flycheck_formatter.cr:4:33
2019-04-14 16:37:03 +00:00
[W] Lint/UnusedArgument: Unused argument `location`
> 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`
> return s += issues.size
^
2017-11-17 18:28:45 +00:00
Finished in 542.64 milliseconds
2017-11-17 18:28:45 +00:00
129 inspected, 2 failures.
```
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
```
Build `bin/ameba` binary within your project directory while running `shards install`.
2017-11-17 18:28:45 +00:00
You may also want to use it on [Travis](travis-ci.org):
```yaml
2017-11-17 18:28:45 +00:00
# .travis.yml
language: crystal
install:
- shards install
script:
- crystal spec
2019-07-18 10:53:04 +00:00
- crystal bin/ameba.cr
```
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
```
### 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
## 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`.
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
```
### 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
```
### Inline disabling
One or more rules or one or more group of rules can be disabled using inline directives:
```crystal
# 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
```
## 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)
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