ameba 1.7.0

### Ameba

Code style linter for Crystal

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

- About
- Usage
  - Watch a tutorial
  - Autocorrection
  - Explain issues
  - Describe rules
- Installation
  - As a project dependency
  - Homebrew
  - Docker
  - From sources
- Configuration
  - Sources
  - Rules
  - Inline disabling
- Editors & integrations
- Credits & inspirations
- Contributors

##
About

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 constructs.

See also Roadmap.

##
Usage

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 `size`
    > return size += issues.size
             ^--^

    src/ameba/formatter/base_formatter.cr:16:7 [Correctable]
    [C] Style/RedundantReturn: Redundant `return` detected
    > return size += issues.size
      ^------------------------^

    Finished in 389.45 milliseconds
    107 inspected, 3 failures

###
Watch a tutorial

🎬 Watch the LuckyCast showing how to use Ameba

###
Autocorrection

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

    $ ameba --fix

###
Explain issues

Ameba allows you to dig deeper into an issue, by showing you details about the issue and the reasoning behind it being reported.

For convenience, you can just copy-paste the `PATH:line:column` string from the report and paste it 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

###
Describe rules

You can use `--describe` flag to get a detailed description of a rule:

    $ ameba --describe Lint/UselessAssign

##
Installation

###
As a project dependency

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

    development_dependencies:
      ameba:
        github: crystal-ameba/ameba

To prioritize runtime performance over compilation time, you can add `ameba` target to the `shard.yml` file:

    targets:
      ameba:
        main: lib/ameba/bin/ameba.cr

And then run:

    $ shards build ameba

Alternatively, skip adding `ameba` target and use `crystal build` command directly:

    $ crystal build -o bin/ameba lib/ameba/bin/ameba.cr

Both of these will result in a compiled binary placed under `bin/ameba` path.

You can also just run the `lib/ameba/bin/ameba.cr` file, compiling it on the fly, which is the slowest option:

    $ lib/ameba/bin/ameba.cr

###
Homebrew

    $ brew tap crystal-ameba/ameba
    $ brew install ameba

###
Docker

Build 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/ameba

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

###
From sources

    $ 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 **/*.ecr]`, meaning it includes all project files with `*.cr` and `*.ecr` extensions.
- `Excluded` section - an array of wildcards (or paths) to exclude from the source list defined by `Globs`. Defaults to `%w[lib]`, meaning it excludes the `lib` folder.

In this example we define default globs and exclude `lib` and `src/compiler` folders:

    Globs:
      - "**/*.cr"
      - "**/*.ecr"

    Excluded:
      - lib
      - src/compiler

Specific sources can be excluded at rule level:

    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:

    $ 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

###
Inline disabling

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

##
Editors & integrations

- Ameba Language Server: ameba-ls
- Vim: vim-crystal, Ale
- Emacs: ameba.el
- Sublime Text: Sublime Linter Ameba
- VS Code: vscode-crystal-ameba
- Zed (via Ameba LS): Crystal — Zed extension
- Codacy: codacy-ameba
- GitHub Actions: github-action

##
Credits & inspirations

- Crystal Language
- Rubocop
- Credo
- Dogma

##
Contributors

- veelenga Vitalii Elenhaupt - creator, maintainer
- Sija Sijawusz Pur Rahnama - contributor, maintainer