Files
Bundle OKF 0.1 · 7 conceitos · acg-box/vibe-style
Open source Repository Open in the app JSON README (API)
About
# Files
- [Agent Context and Documentation Ownership](agent-context.md) - Safe-change boundaries, source-of-truth rules, OpenWiki update workflow, documentation contracts, and validation routing for future repository agents.
- [vibe-style Wiki Quickstart](quickstart.md) - Canonical map for the vibe-style Rust and Swift style checker, its rule contracts, fix engine, integrations, release workflows, and validation routes.
# Directories
- [architecture](architecture/)
- [decisions](decisions/)
- [reference](reference/)
- [runbooks](runbooks/)
- [specifications](specifications/)
Details
- Kind
- OKF bundles
- Topic
- Files & documents
- Publisher
- acg-box
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Open pull requests
- 6
- Last push
- 2026-09-09T00:05:05Z
- Repository state
- ativo
- Language
- Rust
- License
- GPL-3.0
- Added
- 2026-09-08 09:05:43
- Updated
- 2026-09-08 09:05:43
- Origin id
acg-box/vibe-style:openwiki/index.md
README
<div align="center">
# vibe-style
Style checker with Rust syntax and semantic analysis, first-batch Swift checks, and a safe auto-fixer for deterministic code layout.
[](https://spdx.org/licenses/GPL-3.0-only.html)
[](https://github.com/acgxv/vibe-style/actions/workflows/language.yml)
[](https://github.com/acgxv/vibe-style/actions/workflows/release.yml)
[](https://github.com/acgxv/vibe-style/tags)
[](https://github.com/acgxv/vibe-style)
</div>
## Overview
`vibe-style` enforces a strict Rust style contract with stable rule IDs (`RUST-STYLE-*`).
It also includes a conservative first batch of read-only Swift checks with stable
`SWIFT-STYLE-*` rule IDs.
It supports:
- `curate`: check and report violations.
- `tune`: apply safe automatic fixes, then re-check.
- `coverage`: print implemented rule IDs.
The checker implementation is the source of truth for parser- and AST-level edge cases.
## Installation
Methods are listed from easiest to most advanced.
### Install prebuilt binaries (curl)
#### Unix (Linux/macOS)
```sh
VERSION="$(curl -fsSL https://api.github.com/repos/acgxv/vibe-style/releases/latest | grep -oE '"tag_name": "v[^"]+"' | cut -d'"' -f4)"
OS="$(uname -s)"
ARCH="$(uname -m)"
case "${OS}:${ARCH}" in
Linux:x86_64) TARGET="x86_64-unknown-linux-gnu" ;;
Darwin:arm64) TARGET="aarch64-apple-darwin" ;;
*) echo "Unsupported platform: ${OS}/${ARCH}" >&2; exit 1 ;;
esac
ASSET="vibe-style-${TARGET}-${VERSION}.tgz"
curl -fsSLO "https://github.com/acgxv/vibe-style/releases/download/${VERSION}/${ASSET}"
tar -xzf "${ASSET}"
INSTALL_DIR="$HOME/.cargo/bin"
mkdir -p "${INSTALL_DIR}"
install -m 0755 "vibe-style-${TARGET}-${VERSION}/vstyle" "${INSTALL_DIR}/vstyle"
install -m 0755 "vibe-style-${TARGET}-${VERSION}/cargo-vstyle" "${INSTALL_DIR}/cargo-vstyle"
```
#### Windows (PowerShell)
```powershell
$Repo = "acgxv/vibe-style"
$Version = (Invoke-RestMethod -Uri "https://api.github.com/repos/$Repo/releases/latest").tag_name
$Target = "x86_64-pc-windows-msvc"
$Asset = "vibe-style-$Target-$Version.zip"
Invoke-WebRequest -Uri "https://github.com/$Repo/releases/download/$Version/$Asset" -OutFile $Asset
Expand-Archive -Path $Asset -DestinationPath .
$InstallDir = "$env:USERPROFILE\.cargo\bin"
New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
Copy-Item "vibe-style-$Target-$Version\vstyle.exe" "$InstallDir\vstyle.exe" -Force
Copy-Item "vibe-style-$Target-$Version\cargo-vstyle.exe" "$InstallDir\cargo-vstyle.exe" -Force
setx PATH "$env:PATH;$InstallDir"
```
Open a new terminal after running `setx`.
Supported prebuilt targets:
- `x86_64-unknown-linux-gnu`
- `aarch64-apple-darwin`
- `x86_64-pc-windows-msvc`
### GitHub Actions
Use the composite action to install a prebuilt release and run a read-only style check:
```yaml
- uses: actions/checkout@v6
- uses: acgxv/vibe-style@v0.2.5
with:
language: rust
workspace: true
args: --all-features
```
The action runs `vstyle curate --language <language>`, adds `--workspace` when
`workspace: true`, and appends `args`. Use `language: swift` for Swift checks, and use
`version: v0.2.5` when CI should pin a specific `vibe-style` release. Use
`version: checkout` only when the workflow should build `vibe-style` from the action
checkout, such as this repository's own local `uses: ./` workflow.
### Install from crates.io (requires Rust/Cargo)
```sh
# Install both binaries (`vstyle` and `cargo-vstyle`).
cargo install vibe-style
```
After installation, you can use both `vstyle ...` and `cargo vstyle ...`.
### Install prebuilt binaries (cargo-binstall, requires Rust/Cargo)
```sh
# Optional: install cargo-binstall once.
cargo install cargo-binstall
# Then install prebuilt binaries for this crate.
cargo binstall vibe-style
```
### Build from source
```sh
git clone https://github.com/acgxv/vibe-style
cd vibe-style
cargo build --release
```
Binaries:
- `target/release/vstyle`
- `target/release/cargo-vstyle`
### Install as a cargo subcommand (local source)
```sh
cargo install --path . --bin cargo-vstyle
```
After installation, you can run `cargo vstyle ...`.
## Usage
### Basic commands
`curate` and `tune` require an explicit `--language`.
```sh
# Check style.
vstyle curate --language rust
# Apply safe fixes, then re-check.
vstyle tune --language rust
# Same as tune, but fail if violations remain.
vstyle tune --language rust --strict
# Include verbose cache diagnostics in addition to tune progress.
vstyle tune --language rust --verbose
# Print implemented rule IDs.
vstyle coverage
```
`tune` prints progress telemetry to stderr for the initial scan, each fix round, scoped
fix batches, semantic validation, and the final scan when fixes were applied. This
output is emitted even when stderr is redirected so long-running workspace repairs
remain observable in logs.
### Cargo-like target selection
```sh
# Workspace-wide.
vstyle curate --language rust --workspace
# Swift workspace-wide.
vstyle curate --language swift --workspace
# Selected packages.
vstyle tune --language rust -p api -p db-service
# Feature flags.
vstyle tune --language rust -p api --features serde,tracing
vstyle tune --language rust -p api --all-features --no-default-features
```
### Exit behavior
- `curate`
- Exit `0`: no violations.
- Exit `1`: violations found.
- `tune`
- Exit `0`: even if unresolved violations remain.
- Exit `1`: unresolved violations remain and `--strict` is used.
- Internal fix or semantic-validation error: restore all selected source files to their
start-of-command contents, then return a failure.
Use `--language rust` to check Rust files and `--language swift` to check Swift files.
File discovery scans every selected `*.rs` or `*.swift` file that is not matched by Git ignore
rules inside that package scope. Git tracking state is not part of file discovery. With
`--workspace`, Rust files are selected from workspace package roots and Swift files are selected
from the Cargo workspace root.
### CI policy
CI runs the current checkout directly for Rust read-only style verification so the style gate can
reuse the same Cargo build graph as Clippy and tests. The release workflow then runs the composite
action against the exact tag and newly published binary asset before it publishes the crate to
crates.io. Use `vstyle tune` locally when you want to apply safe automatic fixes (for example, via
`cargo make lint`).
### Release benchmark
Release-performance acceptance is based on the locally built `vstyle` binary, not on an installed
`cargo-vstyle` subcommand and not on debug-profile timings.
Use the checked-in harness:
```sh
cargo make bench-release-vstyle
```
By default the harness builds the shipping `final-release` profile from `Cargo.toml` and runs both
`vstyle curate --language rust --workspace` and
`vstyle tune --language rust --workspace --verbose` inside a disposable Git
worktree at the current commit. This keeps `tune` from rewriting the primary checkout while still
preserving the Git ignore boundary used for file discovery.
Treat the checked-in self-host benchmark as a release-path regression guard, not as a universal
microbenchmark for every hotspot. On the current workspace it is usually a no-op `tune`; if
`--verbose` reports `Semantic cache: 0 hit(s), 0 miss(es)`, that run did not enter semantic
validation and should not be used to judge semantic-path changes in `src/style/semantic.rs`.
Use a semantic-positive workload before drawing conclusions about semantic validation performance.
Historical benchmark baseline artifacts are not kept in this repository. Use fresh local runs or
the non-blocking `Benchmarks` workflow artifacts when benchmark evidence matters.
To compare the plain `release` profile diagnostically:
```sh
VSTYLE_BENCH_PROFILE=release cargo make bench-release-vstyle
```
`cargo make lint-vstyle` remains the repo-native style gate, but it is not the release benchmark
source of truth because it routes through language-specific `cargo vstyle curate` tasks and can
resolve to an installed subcommand outside the locally built binary under test.
### Semantic benchmark
Use the semantic-specific harness when a change targets `src/style/semantic.rs` or semantic
validation fallback behavior:
```sh
cargo make bench-semantic-vstyle
```
This harness builds the local release binary once, creates a disposable Git fixture crate
based on the `tests/let_mut_reorder.rs` semantic-validation shape, generates a local `Cargo.lock`,
and runs `vstyle tune --language rust --verbose` twice:
- a cold run after clearing `target/vstyle-cache/semantic`
- a warm rerun after restoring the original fixture sources while keeping the cache directory
Use this semantic benchmark to judge `XY-95`-style work; do not compare semantic-path changes only
against the self-host no-op benchmark above.
Historical semantic benchmark artifacts are not kept in this repository. Use fresh local runs or
the non-blocking `Benchmarks` workflow artifacts when semantic evidence matters.
### Benchmark tracking
The repository also tracks both benchmark harnesses through a non-blocking GitHub Actions workflow.
Use the `Benchmarks` workflow for periodic project-level tracking, scheduled baseline refreshes, and
manual reruns when you want artifact-backed evidence without turning performance into a PR gate.
Use direct current-worktree timings first when a local rule change makes the repository's own
sources newly fixable. The checked-in `bench-release-vstyle` harness builds the current binary but
benchmarks a detached `HEAD` worktree, so self-host drift in uncommitted files must be fixed and
committed before the harness becomes authoritative again.
Use the release benchmark for general workspace-scan, fix-engine, import, module, spacing, or
quality-path changes. Use the semantic benchmark for `src/style/semantic.rs`, semantic cache key
changes, or semantic-validation fallback changes. Run both when a change touches both lanes.
The operational runbook for selecting the right benchmark evidence lives in
`openwiki/runbooks/benchmark-tracking.md`.
## Configuration
There is currently no user configuration file.
Rules are built into the checker.
### Environment variables
- `VSTYLE_MAX_IMPORT_SUGGESTION_ROUNDS`
- Controls how many semantic missing-import suggestion rounds `vstyle tune` will perform.
- Default: `2`.
- Increasing this may fix more missing-import cases but will run additional `cargo check --message-format=json` rounds.
### Semantic cache
- `--verbose` prints semantic cache hit/miss statistics for each command.
- Cache files are written under `target/vstyle-cache/semantic/` and keyed by:
- vstyle version metadata,
- `rustc -Vv` output,
- `Cargo.lock` hash,
- selected cargo options,
- selected `*.rs` style file fingerprints.
## Rule Catalog
### File structure
- `RUST-STYLE-FILE-001`: Do not use `mod.rs`; use flat module files.
### Module layout
- `RUST-STYLE-MOD-001`: Keep top-level item order as `mod`, `use`, `macro_rules!`, `type`, `const`, `static`, `trait`, `enum`, `struct`, `impl`, `fn`.
- `RUST-STYLE-MOD-002`: Place `pub` items before non-`pub` items within the same kind. Visibility boundaries define separate batches and must be separated by exactly one blank line.
- `RUST-STYLE-MOD-003`: Place non-`async` functions before `async` functions at the same visibility.
- `RUST-STYLE-MOD-004`: Do not document modules with outer doc comments on the `mod` declaration; place module docs inside the module with `//!`.
- `RUST-STYLE-MOD-005`: Keep each type adjacent to related `impl` blocks, with no blank line between the type and its first `impl`.
- `RUST-STYLE-MOD-007`: In `#[cfg(test)] mod tests`, remove unused `use super::*;` keep-alive imports during `tune`.
### Serde
- `RUST-STYLE-SERDE-001`: Do not use `#[serde(default)]` on `Option<T>` fields.
### Imports and paths
- `RUST-STYLE-IMPORT-001`: Group imports in this order: standard library, third-party, self/workspace/local-module roots.
- `RUST-STYLE-IMPORT-002`: Use exactly one blank line between groups; do not use import-group header comments; normalize `use a::{b, b::c}` to `use a::{b::{self, c}}`.
- `RUST-STYLE-IMPORT-003`: Do not alias imports, except `as _` keep-alive imports. Trait imports used only for method resolution must use `as _`.
- `RUST-STYLE-IMPORT-004`: Do not import free functions or macros into scope; use qualified paths. If imported symbols are ambiguous, use fully qualified paths.
- `RUST-STYLE-IMPORT-005`: In `error.rs`, do not add `use` imports.
- `RUST-STYLE-IMPORT-006`: Keep `use` items only at file top level or module top level.
- `RUST-STYLE-IMPORT-007`: Do not use glob imports (`use ...::*` or equivalent). Use explicit imports only.
- `RUST-STYLE-IMPORT-008`: For non-function, non-macro symbols in type paths and `#[derive(...)]` attributes, prefer unqualified usage with `use` imports when unambiguous; keep fully qualified paths when ambiguous.
- `RUST-STYLE-IMPORT-009`: If a symbol is both imported and also used via other qualified type paths, stop importing that symbol and use fully qualified paths consistently.
- `RUST-STYLE-IMPORT-010`: Do not use `super` or `self` import prefixes. Rewrite `super` imports to crate-absolute imports (`use crate::...`) when module depth allows it, and rewrite `self::...` imports to direct module paths.
- `RUST-STYLE-IMPORT-011`: Order `#[derive(...)]` entries like imports: `std`/`core`/`alloc` first, then third-party derives, then workspace derives; alphabetize within each group.
- `RUST-STYLE-IMPORT-012`: Do not add crate keep-alive imports `use dep as _;` unless another path in the same package uses that crate.
### Types and generics
- `RUST-STYLE-IMPL-001`: Use `Self` instead of concrete type names in `impl` method signatures.
- `RUST-STYLE-IMPL-003`: Keep `impl` blocks contiguous and ordered as inherent, standard-library traits, third-party traits, then workspace-member traits.
- `RUST-STYLE-GENERICS-001`: Move trait bounds to `where`; do not use inline bounds.
- `RUST-STYLE-GENERICS-002`: Remove unnecessary turbofish when the type is already explicit in a `let` binding.
- `RUST-STYLE-GENERICS-003`: Canonicalize turbofish paths to `Type::<Args>::Assoc` form.
- `RUST-STYLE-TYPE-001`: Do not add type aliases that are only pure renames.
- `RUST-STYLE-LET-001`: Place immutable `let` bindings before mutable ones when the reorder is semantically safe.
### Logging and runtime safety
- `RUST-STYLE-LOG-002`: Use structured logging fields and complete-sentence log messages.
- `RUST-STYLE-RUNTIME-001`: Do not use `unwrap()` in non-test code.
- `RUST-STYLE-RUNTIME-002`: `expect()` must use a clear, user-actionable string literal message.
### Numeric literals
- `RUST-STYLE-NUM-001`: Separate numeric literal suffixes with an underscore (for example, `10_f32`).
- `RUST-STYLE-NUM-002`: Use underscore grouping for integers with more than three digits.
### Readability and spacing
- `RUST-STYLE-READ-002`: Keep functions at or under 120 lines.
- `RUST-STYLE-SPACE-003`: Do not insert blank lines within the same statement type. Use exactly one blank line between different statement types. Keep constant declaration groups compact only within the same visibility batch.
- `RUST-STYLE-SPACE-004`: Insert exactly one blank line before each `return` and before final tail expressions unless the body is a single expression.
### Tests
- `RUST-STYLE-TEST-001`: Use descriptive `snake_case` test names.
- `RUST-STYLE-TEST-002`: Reserve `#[cfg(test)] mod _test` for keep-alive imports only.
### Swift first batch
- `SWIFT-STYLE-FILE-001`: Do not use `mod.swift`; use flat Swift entry files.
- `SWIFT-STYLE-IMPORT-004`: Do not import individual Swift symbols; import modules instead.
- `SWIFT-STYLE-TYPE-001`: Do not add `typealias` declarations that are only pure renames.
- `SWIFT-STYLE-RUNTIME-001`: Do not use force unwraps, force casts, or `try!` in non-test Swift code.
- `SWIFT-STYLE-NUM-002`: Use underscore grouping for integers with more than three digits.
- `SWIFT-STYLE-READ-002`: Keep functions at or under 120 lines.
The governing Swift applicability map lives in `openwiki/specifications/swift-style-rule-applicability.md`.
## Development
This repository uses `cargo make` tasks from `Makefile.toml`.
```sh
# Format.
cargo make fmt
cargo make fmt-check
# Full read-only verification.
cargo make check
# Rust-only clippy check.
cargo make check-rust
# vibe-style read-only check.
cargo make check-vstyle
# Apply lint fixes (clippy + vibe-style).
cargo make lint
# Apply vibe-style fixes.
cargo make lint-vstyle
# Rust tests.
cargo make test-rust
```
## Documentation
Durable repository docs start at `openwiki/quickstart.md`.
Documentation placement and naming rules live in `openwiki/agent-context.md`.
## License
Licensed under [GPL-3.0-only](LICENSE).