# obi1kenobi/cargo-semver-checks architecture

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

- Interactive diagram: https://gitdiagram.com/obi1kenobi/cargo-semver-checks
- Repository: https://github.com/obi1kenobi/cargo-semver-checks

## Overview

##### Project Type & Purpose
- This is a Rust-based command-line tool (a `cargo` subcommand) that lints crate API changes for SemVer violations.
- It reads two versions of a crate (baseline & current), generates rustdoc JSON, executes a suite of “lints” (queries) over the JSON, and emits pass/fail output.

##### File Structure
- Top-level:
- `.github/workflows/…` → CI/CD pipelines
- `scripts/` → shell helpers for versioning, release, test scaffold
- `src/` → core Rust modules: CLI entrypoint, config, JSON generation, query engine, templating, utility code, and lint definitions (`.ron` files)
- `test_crates/` & `test_outputs/` → end-to-end test fixtures & snapshots
- `Cargo.toml` → dependencies (Trustfall, serde, clap, rustdoc JSON)
- Key modules under `src/`:
- `main.rs` → CLI parser & orchestrator
- `config.rs` → reads `Cargo.toml` metadata, env vars, flags
- `callbacks.rs` & `check_release.rs` → decide & fetch baseline version (crates.io, Git, local)
- `rustdoc_gen.rs` → invokes `rustdoc --output-format json` for baseline & current
- `data_generation/` → parse JSON into Rust structs (error.rs, request.rs, progress.rs)
- `lints/` → dozens of `.ron` files, each defines a Trustfall query and metadata (severity, required update)
- `query.rs` → initializes Trustfall engine, executes queries
- `templating.rs` → loads human-readable message templates, applies them to query results
- `util.rs`, `manifest.rs` → helper routines

##### README for Technical Insights
- Confirms use of rustdoc JSON, Trustfall query engine, and the concept of “lints” (one per `.ron` file).
- Describes configuration via `Cargo.toml` metadata and CLI flags.
- CI integration as a GitHub Action.

##### Main Components & Interactions
A. CLI Frontend
- `main.rs`, argument parsing (clap)
- Emits pipeline‐start event

B. Configuration Manager
- `config.rs` reads `package.metadata.cargo-semver-checks` + flags + `RUSTDOCFLAGS`

C. Baseline & Current Version Fetcher
- `callbacks.rs` + `check_release.rs`
- Decides baseline (crates.io registry / Git revision / local path)
- Fetches or resolves source directories

D. Rustdoc JSON Generator
- `rustdoc_gen.rs`
- Spawns `cargo doc --no-deps --document-private-items -- -Z unstable-options --output-format json`
- Produces two JSON files (baseline.json & current.json)

E. JSON Parser & Data Model
- `data_generation/`
- Parses JSON into internal Rust structs representing modules, items, signatures

F. Lint Loader & Query Preparation
- Loads each `.ron` file from `src/lints/`
- Uses `templating.rs` to inject message templates into Trustfall queries

G. Trustfall Query Engine
- `query.rs`
- Registers data from E
- Runs all loaded queries (each query yields zero-or-more violations)

H. Result Aggregator & Formatter
- Collects query results, groups by severity

I. Exit & Reporting
- Emits exit code (`0` if no `deny` lints failed, nonzero otherwise)
- Supports GitHub Action by printing annotations

J. Testing Harness
- `test_crates/`, `test_outputs/`, `tests/`
- Automates end-to-end validation using snapshot tests (`snapshot_tests.rs`)

K. CI/CD & Release Scripts
- `.github/workflows/ci.yml`, `scripts/*.sh`
- Build binaries (`build-binaries.yml`), version bump, publish to crates.io

- CLI → Config → Version Fetcher
- Version Fetcher → Rustdoc JSON Generator → 2× JSON files
- JSON files → Data Parser → In-memory data model
- Data model + Lint definitions → Query Engine → Raw lint findings
- Findings → Formatter → Console/CI output
- Scripts & CI workflows wrap the entire flow

##### Architectural Patterns & Design Principles
- Pipeline architecture: sequential transformation stages
- Plugin-like lints: each lint defined externally as a Trustfall query
- Single executable: no microservices, all modules link in one binary
- Configuration-driven behavior: Cargo.toml metadata, `.ron` files

##### Technologies & Libraries
- Rust, `clap` or `structopt` (CLI parsing)
- `serde_json` for JSON parsing
- `trustfall` engine for query evaluation
- `ron` for lint definitions
- `rustdoc` JSON as data source
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["CLI Frontend"]:::internal
    end

    subgraph "Configuration"
        Config["Configuration Manager"]:::internal
    end

    subgraph "Version Fetch"
        VF["Baseline & Current Version Fetcher"]:::internal
    end

    subgraph "Doc Generation"
        Gen["Rustdoc JSON Generator"]:::internal
    end

    subgraph "Data Model"
        Parser["JSON Parser & Data Model"]:::internal
    end

    subgraph "Lint Preparation"
        Loader["Lint Loader & Query Preparation"]:::internal
    end

    subgraph "Query Engine"
        Engine["Trustfall Query Engine"]:::internal
    end

    subgraph "Aggregation"
        Formatter["Result Aggregator & Formatter"]:::internal
    end

    Exit["Exit & Reporting"]:::internal

    subgraph "Testing Harness"
        TH["Testing Harness"]:::testing
    end

    subgraph "CI/CD & Release"
        CI["CI/CD & Release Scripts"]:::ci
    end

    CRATES["crates.io registry"]:::external
    GIT["Git Repository"]:::external
    RUSTDOC["rustdoc binary"]:::external
    BJSON["baseline.json"]:::artifact
    CJSON["current.json"]:::artifact
    OUTPUT["Console/CI Output"]:::external

    CLI --> Config
    Config --> VF
    VF --> CRATES
    VF --> GIT
    VF --> Gen
    Gen --> RUSTDOC
    Gen --> BJSON
    Gen --> CJSON
    BJSON --> Parser
    CJSON --> Parser
    Parser --> Loader
    Loader --> Engine
    Engine --> Formatter
    Formatter --> OUTPUT
    OUTPUT --> Exit

    CI --> CLI
    CI --> TH

    click CLI "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/main.rs"
    click Config "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/config.rs"
    click VF "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/callbacks.rs"
    click VF "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/check_release.rs"
    click Gen "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/rustdoc_gen.rs"
    click Parser "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/data_generation/mod.rs"
    click Loader "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/src/lints/"
    click Loader "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/templating.rs"
    click Engine "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/query.rs"
    click Formatter "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/util.rs"
    click Formatter "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/templating.rs"
    click Exit "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/main.rs"
    click TH "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/test_crates/"
    click TH "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/test_outputs/"
    click TH "https://github.com/obi1kenobi/cargo-semver-checks/blob/main/src/snapshot_tests.rs"
    click TH "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/tests/"
    click CI "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/.github/workflows/"
    click CI "https://github.com/obi1kenobi/cargo-semver-checks/tree/main/scripts/"

    classDef internal fill:#AED6F1,stroke:#1F618D;
    classDef external fill:#D5DBDB,stroke:#566573;
    classDef artifact fill:#A9DFBF,stroke:#196F3D;
    classDef testing fill:#F5B041,stroke:#B9770E;
    classDef ci fill:#FAD7A0,stroke:#D68910;
```
