# crystal-ameba/ameba architecture

> Architecture diagram of the GitHub repository crystal-ameba/ameba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crystal-ameba/ameba
- Repository: https://github.com/crystal-ameba/ameba

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Ingestion"
        CLIEntry["AMEBA CLI"]:::cli
        CLIParser["CLI Parser"]:::cli
        ConfigFile[(.ameba.yml)]:::config
        ConfigMgr["Config Manager"]:::config
        Glob["Source Discovery"]:::config
    end

    subgraph "Analysis Core"
        Tokenizer["Tokenizer"]:::analysis
        Parser["AST Model"]:::analysis
        Visitors["AST Visitor Pipeline"]:::analysis
        RuleEngine["Rule Engine"]:::analysis
        Inline["Inline Comments Support"]:::support
        Location["Location Metadata Extension"]:::support
    end

    subgraph "Output"
        IssueColl["Issue Collector"]:::output
        Formatter["Formatter"]:::output
        Presenter["Presenter"]:::output
        Stdout(("stdout")):::output
    end

    Runner["Runner (Orchestrator)"]:::orchestrator

    %% Data Flow
    CLIEntry -->|invokes| CLIParser
    CLIParser -->|loads config| ConfigFile
    CLIParser -->|uses| ConfigMgr
    CLIParser -->|starts| Runner
    Runner -->|discovers files| Glob
    Runner -->|tokenizes| Tokenizer
    Tokenizer -->|parses| Parser
    Parser -->|visits AST| Visitors
    Visitors -->|applies rules| RuleEngine
    RuleEngine -->|emits issues| IssueColl
    Runner -->|collects issues| IssueColl
    IssueColl -->|formats issues| Formatter
    Formatter -->|presents via| Presenter
    Presenter -->|outputs| Stdout

    %% Support Links
    Runner -->|checks inline disables| Inline
    Runner -->|reads location metadata| Location

    %% Click Events
    click CLIEntry "https://github.com/crystal-ameba/ameba/blob/master/bin/ameba.cr"
    click CLIParser "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/cli/cmd.cr"
    click ConfigFile "https://github.com/crystal-ameba/ameba/blob/master/.ameba.yml"
    click ConfigMgr "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/config.cr"
    click Glob "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/glob_utils.cr"
    click Tokenizer "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/tokenizer.cr"
    click Parser "https://github.com/crystal-ameba/ameba/tree/master/src/ameba/ast"
    click Visitors "https://github.com/crystal-ameba/ameba/tree/master/src/ameba/ast/visitors"
    click RuleEngine "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/rule/base.cr"
    click IssueColl "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/issue.cr"
    click Formatter "https://github.com/crystal-ameba/ameba/tree/master/src/ameba/formatter"
    click Presenter "https://github.com/crystal-ameba/ameba/tree/master/src/ameba/presenter"
    click Runner "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/runner.cr"
    click Inline "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/inline_comments.cr"
    click Location "https://github.com/crystal-ameba/ameba/blob/master/src/ameba/ext/location.cr"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#9f9,stroke:#333,stroke-width:1px
    classDef analysis fill:#9cf,stroke:#333,stroke-width:1px
    classDef support fill:#ff9,stroke-dasharray: 5 5,stroke:#333
    classDef output fill:#fc9,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#ccc,stroke:#333,stroke-width:1px
```
