{
"markdown": "\n\n# vibe-style\n\nStyle checker with Rust syntax and semantic analysis, first-batch Swift checks, and a safe auto-fixer for deterministic code layout.\n\n[](https://spdx.org/licenses/GPL-3.0-only.html)\n[](https://github.com/acgxv/vibe-style/actions/workflows/language.yml)\n[](https://github.com/acgxv/vibe-style/actions/workflows/release.yml)\n[](https://github.com/acgxv/vibe-style/tags)\n[](https://github.com/acgxv/vibe-style)\n\n
\n\n## Overview\n\n`vibe-style` enforces a strict Rust style contract with stable rule IDs (`RUST-STYLE-*`).\nIt also includes a conservative first batch of read-only Swift checks with stable\n`SWIFT-STYLE-*` rule IDs.\nIt supports:\n\n- `curate`: check and report violations.\n- `tune`: apply safe automatic fixes, then re-check.\n- `coverage`: print implemented rule IDs.\n\nThe checker implementation is the source of truth for parser- and AST-level edge cases.\n\n## Installation\n\nMethods are listed from easiest to most advanced.\n\n### Install prebuilt binaries (curl)\n\n#### Unix (Linux/macOS)\n\n```sh\nVERSION=\"$(curl -fsSL https://api.github.com/repos/acgxv/vibe-style/releases/latest | grep -oE '\"tag_name\": \"v[^\"]+\"' | cut -d'\"' -f4)\"\nOS=\"$(uname -s)\"\nARCH=\"$(uname -m)\"\n\ncase \"${OS}:${ARCH}\" in\n\tLinux:x86_64) TARGET=\"x86_64-unknown-linux-gnu\" ;;\n\tDarwin:arm64) TARGET=\"aarch64-apple-darwin\" ;;\n\t*) echo \"Unsupported platform: ${OS}/${ARCH}\" >&2; exit 1 ;;\nesac\n\nASSET=\"vibe-style-${TARGET}-${VERSION}.tgz\"\ncurl -fsSLO \"https://github.com/acgxv/vibe-style/releases/download/${VERSION}/${ASSET}\"\ntar -xzf \"${ASSET}\"\n\nINSTALL_DIR=\"$HOME/.cargo/bin\"\nmkdir -p \"${INSTALL_DIR}\"\ninstall -m 0755 \"vibe-style-${TARGET}-${VERSION}/vstyle\" \"${INSTALL_DIR}/vstyle\"\ninstall -m 0755 \"vibe-style-${TARGET}-${VERSION}/cargo-vstyle\" \"${INSTALL_DIR}/cargo-vstyle\"\n```\n\n#### Windows (PowerShell)\n\n```powershell\n$Repo = \"acgxv/vibe-style\"\n$Version = (Invoke-RestMethod -Uri \"https://api.github.com/repos/$Repo/releases/latest\").tag_name\n$Target = \"x86_64-pc-windows-msvc\"\n$Asset = \"vibe-style-$Target-$Version.zip\"\n\nInvoke-WebRequest -Uri \"https://github.com/$Repo/releases/download/$Version/$Asset\" -OutFile $Asset\nExpand-Archive -Path $Asset -DestinationPath .\n\n$InstallDir = \"$env:USERPROFILE\\.cargo\\bin\"\nNew-Item -ItemType Directory -Force -Path $InstallDir | Out-Null\n\nCopy-Item \"vibe-style-$Target-$Version\\vstyle.exe\" \"$InstallDir\\vstyle.exe\" -Force\nCopy-Item \"vibe-style-$Target-$Version\\cargo-vstyle.exe\" \"$InstallDir\\cargo-vstyle.exe\" -Force\nsetx PATH \"$env:PATH;$InstallDir\"\n```\n\nOpen a new terminal after running `setx`.\n\nSupported prebuilt targets:\n\n- `x86_64-unknown-linux-gnu`\n- `aarch64-apple-darwin`\n- `x86_64-pc-windows-msvc`\n\n### GitHub Actions\n\nUse the composite action to install a prebuilt release and run a read-only style check:\n\n```yaml\n- uses: actions/checkout@v6\n- uses: acgxv/vibe-style@v0.2.5\n with:\n language: rust\n workspace: true\n args: --all-features\n```\n\nThe action runs `vstyle curate --language `, adds `--workspace` when\n`workspace: true`, and appends `args`. Use `language: swift` for Swift checks, and use\n`version: v0.2.5` when CI should pin a specific `vibe-style` release. Use\n`version: checkout` only when the workflow should build `vibe-style` from the action\ncheckout, such as this repository's own local `uses: ./` workflow.\n\n### Install from crates.io (requires Rust/Cargo)\n\n```sh\n# Install both binaries (`vstyle` and `cargo-vstyle`).\ncargo install vibe-style\n```\n\nAfter installation, you can use both `vstyle ...` and `cargo vstyle ...`.\n\n### Install prebuilt binaries (cargo-binstall, requires Rust/Cargo)\n\n```sh\n# Optional: install cargo-binstall once.\ncargo install cargo-binstall\n\n# Then install prebuilt binaries for this crate.\ncargo binstall vibe-style\n```\n\n### Build from source\n\n```sh\ngit clone https://github.com/acgxv/vibe-style\ncd vibe-style\ncargo build --release\n```\n\nBinaries:\n\n- `target/release/vstyle`\n- `target/release/cargo-vstyle`\n\n### Install as a cargo subcommand (local source)\n\n```sh\ncargo install --path . --bin cargo-vstyle\n```\n\nAfter installation, you can run `cargo vstyle ...`.\n\n## Usage\n\n### Basic commands\n\n`curate` and `tune` require an explicit `--language`.\n\n```sh\n# Check style.\nvstyle curate --language rust\n\n# Apply safe fixes, then re-check.\nvstyle tune --language rust\n\n# Same as tune, but fail if violations remain.\nvstyle tune --language rust --strict\n\n# Include verbose cache diagnostics in addition to tune progress.\nvstyle tune --language rust --verbose\n\n# Print implemented rule IDs.\nvstyle coverage\n```\n\n`tune` prints progress telemetry to stderr for the initial scan, each fix round, scoped\nfix batches, semantic validation, and the final scan when fixes were applied. This\noutput is emitted even when stderr is redirected so long-running workspace repairs\nremain observable in logs.\n\n### Cargo-like target selection\n\n```sh\n# Workspace-wide.\nvstyle curate --language rust --workspace\n\n# Swift workspace-wide.\nvstyle curate --language swift --workspace\n\n# Selected packages.\nvstyle tune --language rust -p api -p db-service\n\n# Feature flags.\nvstyle tune --language rust -p api --features serde,tracing\nvstyle tune --language rust -p api --all-features --no-default-features\n```\n\n### Exit behavior\n\n- `curate`\n - Exit `0`: no violations.\n - Exit `1`: violations found.\n- `tune`\n - Exit `0`: even if unresolved violations remain.\n - Exit `1`: unresolved violations remain and `--strict` is used.\n - Internal fix or semantic-validation error: restore all selected source files to their\n start-of-command contents, then return a failure.\n\nUse `--language rust` to check Rust files and `--language swift` to check Swift files.\nFile discovery scans every selected `*.rs` or `*.swift` file that is not matched by Git ignore\nrules inside that package scope. Git tracking state is not part of file discovery. With\n`--workspace`, Rust files are selected from workspace package roots and Swift files are selected\nfrom the Cargo workspace root.\n\n### CI policy\n\nCI runs the current checkout directly for Rust read-only style verification so the style gate can\nreuse the same Cargo build graph as Clippy and tests. The release workflow then runs the composite\naction against the exact tag and newly published binary asset before it publishes the crate to\ncrates.io. Use `vstyle tune` locally when you want to apply safe automatic fixes (for example, via\n`cargo make lint`).\n\n### Release benchmark\n\nRelease-performance acceptance is based on the locally built `vstyle` binary, not on an installed\n`cargo-vstyle` subcommand and not on debug-profile timings.\n\nUse the checked-in harness:\n\n```sh\ncargo make bench-release-vstyle\n```\n\nBy default the harness builds the shipping `final-release` profile from `Cargo.toml` and runs both\n`vstyle curate --language rust --workspace` and\n`vstyle tune --language rust --workspace --verbose` inside a disposable Git\nworktree at the current commit. This keeps `tune` from rewriting the primary checkout while still\npreserving the Git ignore boundary used for file discovery.\n\nTreat the checked-in self-host benchmark as a release-path regression guard, not as a universal\nmicrobenchmark for every hotspot. On the current workspace it is usually a no-op `tune`; if\n`--verbose` reports `Semantic cache: 0 hit(s), 0 miss(es)`, that run did not enter semantic\nvalidation and should not be used to judge semantic-path changes in `src/style/semantic.rs`.\nUse a semantic-positive workload before drawing conclusions about semantic validation performance.\n\nHistorical benchmark baseline artifacts are not kept in this repository. Use fresh local runs or\nthe non-blocking `Benchmarks` workflow artifacts when benchmark evidence matters.\n\nTo compare the plain `release` profile diagnostically:\n\n```sh\nVSTYLE_BENCH_PROFILE=release cargo make bench-release-vstyle\n```\n\n`cargo make lint-vstyle` remains the repo-native style gate, but it is not the release benchmark\nsource of truth because it routes through language-specific `cargo vstyle curate` tasks and can\nresolve to an installed subcommand outside the locally built binary under test.\n\n### Semantic benchmark\n\nUse the semantic-specific harness when a change targets `src/style/semantic.rs` or semantic\nvalidation fallback behavior:\n\n```sh\ncargo make bench-semantic-vstyle\n```\n\nThis harness builds the local release binary once, creates a disposable Git fixture crate\nbased on the `tests/let_mut_reorder.rs` semantic-validation shape, generates a local `Cargo.lock`,\nand runs `vstyle tune --language rust --verbose` twice:\n\n- a cold run after clearing `target/vstyle-cache/semantic`\n- a warm rerun after restoring the original fixture sources while keeping the cache directory\n\nUse this semantic benchmark to judge `XY-95`-style work; do not compare semantic-path changes only\nagainst the self-host no-op benchmark above.\n\nHistorical semantic benchmark artifacts are not kept in this repository. Use fresh local runs or\nthe non-blocking `Benchmarks` workflow artifacts when semantic evidence matters.\n\n### Benchmark tracking\n\nThe repository also tracks both benchmark harnesses through a non-blocking GitHub Actions workflow.\nUse the `Benchmarks` workflow for periodic project-level tracking, scheduled baseline refreshes, and\nmanual reruns when you want artifact-backed evidence without turning performance into a PR gate.\n\nUse direct current-worktree timings first when a local rule change makes the repository's own\nsources newly fixable. The checked-in `bench-release-vstyle` harness builds the current binary but\nbenchmarks a detached `HEAD` worktree, so self-host drift in uncommitted files must be fixed and\ncommitted before the harness becomes authoritative again.\n\nUse the release benchmark for general workspace-scan, fix-engine, import, module, spacing, or\nquality-path changes. Use the semantic benchmark for `src/style/semantic.rs`, semantic cache key\nchanges, or semantic-validation fallback changes. Run both when a change touches both lanes.\n\nThe operational runbook for selecting the right benchmark evidence lives in\n`openwiki/runbooks/benchmark-tracking.md`.\n\n## Configuration\n\nThere is currently no user configuration file.\nRules are built into the checker.\n\n### Environment variables\n\n- `VSTYLE_MAX_IMPORT_SUGGESTION_ROUNDS`\n - Controls how many semantic missing-import suggestion rounds `vstyle tune` will perform.\n - Default: `2`.\n - Increasing this may fix more missing-import cases but will run additional `cargo check --message-format=json` rounds.\n\n### Semantic cache\n\n- `--verbose` prints semantic cache hit/miss statistics for each command.\n- Cache files are written under `target/vstyle-cache/semantic/` and keyed by:\n - vstyle version metadata,\n - `rustc -Vv` output,\n - `Cargo.lock` hash,\n - selected cargo options,\n - selected `*.rs` style file fingerprints.\n\n## Rule Catalog\n\n### File structure\n\n- `RUST-STYLE-FILE-001`: Do not use `mod.rs`; use flat module files.\n\n### Module layout\n\n- `RUST-STYLE-MOD-001`: Keep top-level item order as `mod`, `use`, `macro_rules!`, `type`, `const`, `static`, `trait`, `enum`, `struct`, `impl`, `fn`.\n- `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.\n- `RUST-STYLE-MOD-003`: Place non-`async` functions before `async` functions at the same visibility.\n- `RUST-STYLE-MOD-004`: Do not document modules with outer doc comments on the `mod` declaration; place module docs inside the module with `//!`.\n- `RUST-STYLE-MOD-005`: Keep each type adjacent to related `impl` blocks, with no blank line between the type and its first `impl`.\n- `RUST-STYLE-MOD-007`: In `#[cfg(test)] mod tests`, remove unused `use super::*;` keep-alive imports during `tune`.\n\n### Serde\n\n- `RUST-STYLE-SERDE-001`: Do not use `#[serde(default)]` on `Option` fields.\n\n### Imports and paths\n\n- `RUST-STYLE-IMPORT-001`: Group imports in this order: standard library, third-party, self/workspace/local-module roots.\n- `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}}`.\n- `RUST-STYLE-IMPORT-003`: Do not alias imports, except `as _` keep-alive imports. Trait imports used only for method resolution must use `as _`.\n- `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.\n- `RUST-STYLE-IMPORT-005`: In `error.rs`, do not add `use` imports.\n- `RUST-STYLE-IMPORT-006`: Keep `use` items only at file top level or module top level.\n- `RUST-STYLE-IMPORT-007`: Do not use glob imports (`use ...::*` or equivalent). Use explicit imports only.\n- `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.\n- `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.\n- `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.\n- `RUST-STYLE-IMPORT-011`: Order `#[derive(...)]` entries like imports: `std`/`core`/`alloc` first, then third-party derives, then workspace derives; alphabetize within each group.\n- `RUST-STYLE-IMPORT-012`: Do not add crate keep-alive imports `use dep as _;` unless another path in the same package uses that crate.\n\n### Types and generics\n\n- `RUST-STYLE-IMPL-001`: Use `Self` instead of concrete type names in `impl` method signatures.\n- `RUST-STYLE-IMPL-003`: Keep `impl` blocks contiguous and ordered as inherent, standard-library traits, third-party traits, then workspace-member traits.\n- `RUST-STYLE-GENERICS-001`: Move trait bounds to `where`; do not use inline bounds.\n- `RUST-STYLE-GENERICS-002`: Remove unnecessary turbofish when the type is already explicit in a `let` binding.\n- `RUST-STYLE-GENERICS-003`: Canonicalize turbofish paths to `Type::::Assoc` form.\n- `RUST-STYLE-TYPE-001`: Do not add type aliases that are only pure renames.\n- `RUST-STYLE-LET-001`: Place immutable `let` bindings before mutable ones when the reorder is semantically safe.\n\n### Logging and runtime safety\n\n- `RUST-STYLE-LOG-002`: Use structured logging fields and complete-sentence log messages.\n- `RUST-STYLE-RUNTIME-001`: Do not use `unwrap()` in non-test code.\n- `RUST-STYLE-RUNTIME-002`: `expect()` must use a clear, user-actionable string literal message.\n\n### Numeric literals\n\n- `RUST-STYLE-NUM-001`: Separate numeric literal suffixes with an underscore (for example, `10_f32`).\n- `RUST-STYLE-NUM-002`: Use underscore grouping for integers with more than three digits.\n\n### Readability and spacing\n\n- `RUST-STYLE-READ-002`: Keep functions at or under 120 lines.\n- `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.\n- `RUST-STYLE-SPACE-004`: Insert exactly one blank line before each `return` and before final tail expressions unless the body is a single expression.\n\n### Tests\n\n- `RUST-STYLE-TEST-001`: Use descriptive `snake_case` test names.\n- `RUST-STYLE-TEST-002`: Reserve `#[cfg(test)] mod _test` for keep-alive imports only.\n\n### Swift first batch\n\n- `SWIFT-STYLE-FILE-001`: Do not use `mod.swift`; use flat Swift entry files.\n- `SWIFT-STYLE-IMPORT-004`: Do not import individual Swift symbols; import modules instead.\n- `SWIFT-STYLE-TYPE-001`: Do not add `typealias` declarations that are only pure renames.\n- `SWIFT-STYLE-RUNTIME-001`: Do not use force unwraps, force casts, or `try!` in non-test Swift code.\n- `SWIFT-STYLE-NUM-002`: Use underscore grouping for integers with more than three digits.\n- `SWIFT-STYLE-READ-002`: Keep functions at or under 120 lines.\n\nThe governing Swift applicability map lives in `openwiki/specifications/swift-style-rule-applicability.md`.\n\n## Development\n\nThis repository uses `cargo make` tasks from `Makefile.toml`.\n\n```sh\n# Format.\ncargo make fmt\ncargo make fmt-check\n\n# Full read-only verification.\ncargo make check\n\n# Rust-only clippy check.\ncargo make check-rust\n\n# vibe-style read-only check.\ncargo make check-vstyle\n\n# Apply lint fixes (clippy + vibe-style).\ncargo make lint\n\n# Apply vibe-style fixes.\ncargo make lint-vstyle\n\n# Rust tests.\ncargo make test-rust\n```\n\n## Documentation\n\nDurable repository docs start at `openwiki/quickstart.md`.\nDocumentation placement and naming rules live in `openwiki/agent-context.md`.\n\n## License\n\nLicensed under [GPL-3.0-only](LICENSE).\n",
"bytes": 17314,
"sha": "a1c9624e4cfe010726e5d7328ded7b198dee5edfce4569d7132c97ee0197fe7b",
"repo_slug": "acg-box/vibe-style",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_acg_box_vibe_style_openwiki_index_md_48d76149/readme"
}