How obi1kenobi/cargo-semver-checks works
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