How crystal-ameba/ameba works
Project type and purpose
• Project type: A standalone, command-line, static analysis tool (a linter) for the Crystal programming language.
• Purpose: Discover Crystal source files in a project, parse them into an AST, run a battery of style/lint/type rules against that AST, collect “issues,” and report or autocorrect them via various output formatters.
File structure
Top-level:
• bin/ameba.cr – CLI entrypoint
• src/ameba – core modules, organized into subfolders:
– cli (command & flag parsing)
– config (loading .ameba.yml)
– glob_utils (source-file discovery)
– tokenizer & spec/tokenizer – lexical analysis
– ast & ast/visitors – AST model + Visitor implementations
– rule/* – definitions for Lint, Style, Metrics, Naming, Performance, Typing, Documentation, Layout
– runner.cr – orchestrates scanning, parsing, rule evaluation
– issue.cr & reportable.cr – issue data models
– formatter/* – Strategy implementations for console, JSON, GitHub Actions, etc.
– presenter/* – transforms rule sets & issues into output data
– inline_comments & ext/location – support inline disabling & location metadata
• spec – full suite of unit tests mirroring each source module
• .ameba.yml – default configuration schema
• Dockerfile, Makefile, CI/CD workflows – deployment & automation
README for additional insights
• Describes main features: run linter, --fix, --explain, parallel workers.
• Documents configuration layers: global globs, per-rule settings, inline disabling.
• Mentions integrations (editors, GitHub Actions, Docker).
a. Main components (each as a rectangle):
• CLI Layer (bin/ameba.cr + CLI parser)
• Configuration Manager (.ameba.yml, src/ameba/config.cr)
• Source Discovery (glob_utils)
• Tokenizer & Parser (tokenizer + AST constructors)
• AST Visitor Pipeline (all ast/visitors)
• Rule Engine (registry of rule/* modules)
• Issue Collector (issue.cr, reportable.cr)
• Formatter & Presenter (all formatter/* & presenter/*)
• Runner (orchestrator tying everything together)
1. User invokes ameba CLI →
2. CLI Layer reads flags →
3. Config Manager loads .ameba.yml →
4. Runner uses Glob Utils to build file list →
5. For each file:
• Tokenizer produces tokens →
• Parser builds AST →
• AST passes through Visitor Pipeline (collect scopes, flows, metrics) →
• Rule Engine iterates over AST/visitor output →
• Issues emitted to Issue Collector →
6. Runner sends collected Issues to Formatter & Presenter →
7. Formatted output to stdout or write modifications if --fix.
c. Architectural patterns & principles:
• Visitor pattern for AST traversal and data collection
• Strategy pattern for pluggable Formatters
• Registry / Factory pattern for rule discovery and instantiation
• Pipeline (chain-of-responsibility) for token→AST→visitor→rule stages
• Separation of concerns: CLI vs config vs analysis vs formatting
d. Key technologies & libraries:
• Crystal language, Shard-based packaging (shard.yml)
• Docker & GitHub Actions for CI/CD
• Ameba itself as a dependency for other Crystal projects
Elements
• Blue rectangles for core analysis modules
• Green rectangles for config & discovery
• Yellow rectangles for I/O/CLI/Formatter
Detailed separation of components
• Strategy plug-in point where adding a new Formatter or Rule module fits into the pipeline (emphasize extensibility).