awesome

Is your Crystal code awesome — or awful?

awesome is a next-generation semantic linter for Crystal. Where ameba checks style, awesome checks semantics and real best practices — the kind of things that make code faster or slower, not just prettier.

• Guards, not cops. Every check is a guard: semantic, documented, configured in awesome.yml (rubocop.yml-style).
• The compiler's own AST. awesome parses with Crystal::Parser — the exact AST crystal build sees. No reimplementation, no drift.
• Documentation lives in the guard. awesome doc prints each guard's short description, good example and bad example — straight from the source of truth.
• Zero dependencies. Just Crystal.

Install

With carat:

$ carat install OrelSokolov/awesome.cr
$ awesome

Or from a checkout:

$ git clone https://github.com/OrelSokolov/awesome.cr && cd awesome.cr
$ crystal build --release bin/awesome.cr -o bin/awesome

Usage

$ awesome                 # check the current directory (all guards)
$ awesome speed           # speed guards only
$ awesome memory src lib/ # memory guards on specific paths
$ awesome code src/       # code guards only
$ awesome --level psycho  # micro-optimization guards too (readability be damned)
$ awesome src foo.cr      # check specific paths
$ awesome doc             # documentation for all guards
$ awesome doc StructurePacking
$ awesome guards          # registered guards: total, by level and kind

Output:

src/demo.cr:1:1
> struct Frame
[StructurePacking] Reorder struct fields by decreasing alignment (largest first): sizeof can shrink from 56 to 48 bytes

1 inspected, 1 issue.
Your code is awful: 1 issue.

Exit status: 0 — awesome, 1 — awful, 2 — error. CI-ready.

Issues are colored by severity — how serious a finding is:

• bug (red) — the code is broken at runtime: leaked or double-freed C memory, undefined behaviour.
• warning (yellow) — a real problem worth fixing: wasted allocations, O(n) traps, eager work.
• style (magenta) — design/idiom nits (smells): the code works, it just reads worse.

Check levels

Every guard has a level — how much it asks of your code. The level picks the audience: pick by how long the code is going to live.

Levels are cumulative: a run at level N executes every guard at level N or below. awesome checks up to senior by default. To go all the way (or strip down to the essentials):

$ awesome --level psycho
$ awesome --level vibecoder

Or set it once in awesome.yml (a per-guard enabled: true still turns a single psycho guard on without raising the global level):

level: psycho

Configuration

Drop an awesome.yml in your project root (rubocop.yml-style, guards instead of cops). Without one, awesome runs all guards with sane defaults:

include:
  - src/**/*.cr

exclude:
  - lib/**

guards:
  StructurePacking:
    enabled: true
    check_extern: false

Guards

Development

$ crystal spec        # run the test suite
$ crystal build bin/awesome.cr

examples/awful/ is a live demo: the bad snippets of every guard, one file per guard (a file may hold several examples of its guard). crystal spec asserts each guard fires on its own file — and nothing else fires there; run the binary to see the report:

$ bin/awesome examples/awful

A guard is a class in src/awesome/guards/:

class Awesome::Guards::MyGuard < Awesome::Guard
  KIND              = "speed" # or "memory", "code"
  LEVEL             = "senior" # or "vibecoder", "psycho" (senior is the default)
  SEVERITY          = "warning" # or "bug", "style" (warning by default; code kind → style)
  SHORT_DESCRIPTION = "..."
  GOOD_EXAMPLE      = "..."
  BAD_EXAMPLE       = "..."

  def test(source : Awesome::Source, config : Awesome::GuardConfig) : Array(Awesome::Issue)
    visitor = MyVisitor.new(source)
    source.ast.try &.accept(visitor)
    visitor.issues
  end
end

Awesome::Guard.registered << Awesome::Guards::MyGuard

See ROADMAP.md for what's next (search modes, more guards).

License

MIT — see LICENSE.