Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/crystal-ameba/ameba

A static code analysis tool for Crystal
https://github.com/crystal-ameba/ameba

ameba code-analysis crystal linter static-analysis

Last synced: 8 days ago
JSON representation

A static code analysis tool for Crystal

Awesome Lists containing this project

README 

        


  

  
Ameba


  
Code style linter for Crystal


  


    

      (a single-celled animal that catches food and moves about by extending fingerlike projections of protoplasm)

    

  


  


    

    

    

  



- [About](#about)

- [Usage](#usage)

  - [Watch a tutorial](#watch-a-tutorial)

  - [Autocorrection](#autocorrection)

  - [Explain issues](#explain-issues)

  - [Run in parallel](#run-in-parallel)

- [Installation](#installation)

  - [As a project dependency:](#as-a-project-dependency)

  - [OS X](#os-x)

  - [Docker](#docker)

  - [From sources](#from-sources)

- [Configuration](#configuration)

  - [Sources](#sources)

  - [Rules](#rules)

  - [Inline disabling](#inline-disabling)

- [Editors \& integrations](#editors--integrations)

- [Credits \& inspirations](#credits--inspirations)

- [Contributors](#contributors)



## About



Ameba is a static code analysis tool for the Crystal language.

It enforces a consistent [Crystal code style](https://crystal-lang.org/reference/conventions/coding_style.html),

also catches code smells and wrong code constructions.



See also [Roadmap](https://github.com/crystal-ameba/ameba/wiki).



## Usage



Run `ameba` binary within your project directory to catch code issues:



```sh

$ 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 a tutorial






[🎬 Watch the LuckyCast showing how to use Ameba](https://luckycasts.com/videos/ameba)



### Autocorrection



Rules that are marked as `[Correctable]` in the output can be automatically corrected using `--fix` flag:



```sh

$ ameba --fix

```



### Explain issues



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.



```sh

$ ameba crystal/command/format.cr:26:83           # show explanation for the issue

$ ameba --explain crystal/command/format.cr:26:83 # same thing

```



### Run in parallel



Some quick benchmark results measured while running Ameba on Crystal repo:



```sh

$ 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

```



## Installation



### As a project dependency:



Add this to your application's `shard.yml`:



```yaml

development_dependencies:

  ameba:

    github: crystal-ameba/ameba

```



Build `bin/ameba` binary within your project directory while running `shards install`.



### OS X



```sh

$ brew tap crystal-ameba/ameba

$ brew install ameba

```



### Docker



Build the image:



```sh

$ 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`:



```sh

$ docker run -v $(pwd):/src ghcr.io/crystal-ameba/ameba

```



Also available on GitHub: https://github.com/crystal-ameba/ameba/pkgs/container/ameba



### From sources



```sh

$ git clone https://github.com/crystal-ameba/ameba && cd ameba

$ make install

```



## Configuration



Default 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`.



### Sources



**List of sources to run Ameba on can be configured globally via:**



- `Globs` section - an array of wildcards (or paths) to include to the

  inspection. Defaults to `%w[**/*.cr !lib]`, meaning it includes all project

  files with `*.cr` extension except those which exist in `lib` folder.

- `Excluded` section - 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 `src/compiler` folder:



``` yaml

Globs:

  - "**/*.cr"

  - "!lib"



Excluded:

  - src/compiler

```



**Specific sources can be excluded at rule level**:



``` yaml

Style/RedundantBegin:

  Excluded:

    - src/server/processor.cr

    - src/server/api.cr

```



### Rules



One or more rules, or a one or more group of rules can be included or excluded

via command line arguments:



```sh

$ 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:



``` yaml

Style/RedundantBegin:

  Enabled: false

```



### 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

```



## Editors & integrations



- Vim: [vim-crystal](https://github.com/rhysd/vim-crystal), [Ale](https://github.com/w0rp/ale)

- Emacs: [ameba.el](https://github.com/crystal-ameba/ameba.el)

- Sublime Text: [Sublime Linter Ameba](https://github.com/epergo/SublimeLinter-contrib-ameba)

- VSCode: [vscode-crystal-ameba](https://github.com/crystal-ameba/vscode-crystal-ameba)

- Codacy: [codacy-ameba](https://github.com/codacy/codacy-ameba)

- GitHub Actions: [github-action](https://github.com/crystal-ameba/github-action)



## Credits & inspirations



- [Crystal Language](https://crystal-lang.org)

- [Rubocop](https://rubocop.org)

- [Credo](http://credo-ci.org)

- [Dogma](https://github.com/lpil/dogma)



## Contributors



- [veelenga](https://github.com/veelenga) Vitalii Elenhaupt - creator, maintainer

- [Sija](https://github.com/Sija) Sijawusz Pur Rahnama - contributor, maintainer