|
| 1 | +This file provides guidance to AI coding agents when working with code in this repository. |
| 2 | + |
| 3 | +## What this project is |
| 4 | + |
| 5 | +`pks` is a Rust CLI tool — a high-performance reimplementation of Shopify's [packwerk](https://github.com/Shopify/packwerk) Ruby gem. It checks boundaries between Ruby "packs" (packages) in a modular Rails/Ruby application. The binary is named `pks`; the Rust library crate is named `packs`. |
| 6 | + |
| 7 | +## Commands |
| 8 | + |
| 9 | +```bash |
| 10 | +# Build |
| 11 | +cargo build |
| 12 | +cargo build --release |
| 13 | + |
| 14 | +# Run all tests |
| 15 | +cargo test |
| 16 | + |
| 17 | +# Run a single test by name |
| 18 | +cargo test test_name |
| 19 | + |
| 20 | +# Run a specific integration test file |
| 21 | +cargo test --test check_test |
| 22 | + |
| 23 | +# Lint |
| 24 | +cargo clippy --all-targets --all-features |
| 25 | +cargo fmt --all -- --check # check only |
| 26 | +cargo fmt --all # apply formatting |
| 27 | + |
| 28 | +# Check compilation without building |
| 29 | +cargo check |
| 30 | +``` |
| 31 | + |
| 32 | +Rustfmt is configured with `max_width=80` (`.rustfmt.toml`). CI runs clippy with `-Dwarnings` so all warnings are errors. |
| 33 | + |
| 34 | +## Architecture |
| 35 | + |
| 36 | +### Entry points |
| 37 | +- `src/main.rs` — calls `cli::run()`, maps errors to exit codes (0 = ok, 1 = violations found, 2 = internal error) |
| 38 | +- `src/lib.rs` — exposes `pub mod packs::cli` for the `serde_magnus` Ruby FFI consumers |
| 39 | +- `src/packs.rs` — module declarations and top-level public functions (`check`, `update`, `validate`, `add_dependency`, etc.) |
| 40 | + |
| 41 | +### Key modules |
| 42 | +- `src/packs/cli.rs` — CLI argument parsing with `clap`. Builds `Configuration`, dispatches to `packs::*` functions. |
| 43 | +- `src/packs/configuration.rs` — `Configuration` struct (the central data object passed everywhere). Built from `packwerk.yml` via `raw_configuration.rs` + `walk_directory.rs`. |
| 44 | +- `src/packs/checker.rs` — Core violation-checking engine. Defines `CheckerInterface` and `ValidatorInterface` traits, `Violation`/`ViolationIdentifier` types, and `check_all()`/`update()`/`validate_all()`. |
| 45 | +- `src/packs/checker/` — Individual checkers: `dependency`, `privacy`, `visibility`, `layer`, `folder_privacy`. Each implements `CheckerInterface`. |
| 46 | +- `src/packs/parsing/` — File parsing. Two modes: |
| 47 | + - **Packwerk mode** (default): Zeitwerk-based constant resolution from file paths (`parsing/ruby/zeitwerk/`) |
| 48 | + - **Experimental mode** (`--experimental-parser`): AST-based using `lib-ruby-parser` (`parsing/ruby/experimental/`) |
| 49 | + - Both Ruby (`.rb`, `.rake`, `Gemfile`, `.gemspec`) and ERB (`.erb`) are supported. |
| 50 | +- `src/packs/pack.rs` / `pack_set.rs` — `Pack` struct (represents one `package.yml`) and `PackSet` (the collection). |
| 51 | +- `src/packs/package_todo.rs` — Read/write `package_todo.yml` files that record allowed violations. |
| 52 | +- `src/packs/caching/` — Per-file MD5-based cache for parsed results (`tmp/cache/packwerk/` by default). `--no-cache` disables it. |
| 53 | + |
| 54 | +### Data flow for `check` |
| 55 | +1. `configuration::get()` reads `packwerk.yml`, walks the directory tree, builds `PackSet` and `Configuration`. |
| 56 | +2. `reference_extractor::get_all_references()` processes files in parallel (via `rayon`), extracting `Reference` objects. |
| 57 | +3. Each `CheckerInterface` impl runs against every reference to produce `Violation`s. |
| 58 | +4. `CheckAllBuilder` separates violations into reportable, stale, and strict-mode violations by comparing against recorded violations in `package_todo.yml`. |
| 59 | +5. Output is formatted via `text.rs` (packwerk format), `csv.rs`, or `json.rs`. |
| 60 | + |
| 61 | +### Tests |
| 62 | +Integration tests live in `tests/` and use fixture Ruby apps in `tests/fixtures/`. The `tests/common/mod.rs` provides shared test helpers. Most tests use `assert_cmd` to invoke the compiled binary. |
0 commit comments