High-performance Rust toolkit for OpenAPI (3.0, 3.1, 3.2; 2.0 read via family
sniffing), Arazzo 1.0, and Overlay 1.0: lossless tree-sitter parsing, native
$ref resolution with cycle classification, JSON Schema 2020-12 validation,
Spectral-compatible linting, an LSP server, and a CLI.
Design constraints: parse once, view many; zero-copy scalars; arena-indexed nodes; lazy memoized resolution. Benchmarks with honest budget verdicts live in BENCHMARKS.md.
SDK generation uses one source-addressed contract pipeline for twelve native backends — TypeScript/JavaScript, Python, Go, Rust, Swift, Java, Kotlin, C#, Ruby, PHP, Dart and C++ — producing native models, checked codecs, HTTP operations, packages, golden-defaults behavior (attribution, pagination, OAuth, env-credential defaults) and documentation. Start with the SDK generation guide; the SDK capabilities page compares the backends.
No release has been tagged yet. Until v0.1.0 is published, install from
source (the last command below); the installers, the Homebrew formula and
the release download of the GitHub Action start working with that release.
Prebuilt binaries for macOS, Linux (glibc and static musl) and Windows are attached to every release (Windows is tier 2 until one release has passed its smoke tests):
# macOS and Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/LukasParke/suspect/releases/latest/download/suspect-cli-installer.sh | sh
# Homebrew
brew install LukasParke/tap/suspect
# Windows
powershell -ExecutionPolicy Bypass -c "irm https://github.com/LukasParke/suspect/releases/latest/download/suspect-cli-installer.ps1 | iex"
# From source (needs Rust)
cargo install --locked --git https://github.com/LukasParke/suspect suspect-cli
suspect --versionThe installers put suspect in ~/.cargo/bin, the same place cargo install uses. Each archive (suspect-cli-<target>.tar.gz, .zip on
Windows) has a .sha256 file next to it, and gh attestation verify <file> --repo LukasParke/suspect checks its build provenance.
In GitHub Actions, LukasParke/suspect/.github/actions/suspect@v<version>
downloads the release binary and can run check, test or gen
(action.yml). Referenced by branch
or commit with version: source, it builds the CLI from that revision
instead, which needs no release.
Check a spec. check runs every check the editor runs and exits 1 on errors;
validate and lint are filtered views of it:
$ suspect check api.yaml
api.yaml:8:7 [WARNING] oas-operation-missing-operationId: get operation is missing an operationId
how to fix: Add an `operationId` so generated SDK methods carry a stable name.
$ suspect check api.yaml --format sarif --baseline .suspect-baseline.jsonSettings live in one file, .suspect.yaml, read by every command, CI and the
editor; suspect config --explain shows each value and where it came from.
Findings can be suppressed inline or recorded in a baseline
(linting guide).
Open the same spec in an editor. suspect lsp serves diagnostics, $ref
navigation across files, hover, completion, rename, quick fixes, formatting,
semantic highlighting and inlay hints to VS Code, Zed, Neovim, Helix and
Emacs (editors guide):
Generate an SDK, docs or your own templates:
$ suspect gen sdk crates/suspect-codegen/tests/fixtures/m2/canonical.openapi.yaml \
--profile typescript-http --package-name @example/widgets \
--package-version 0.1.0 -o generated
$ suspect gen docs api.yaml --style markdown -o docs/apisuspect gen profiles lists the twelve backends. --check makes gen sdk,
gen template and the other file generators a read-only drift check
(SDK generation,
docs generation).
Run Arazzo workflows as contract tests or load tests, live or against recorded traffic. Every reply is held to the response its operation declares (status, content type, required headers, body schema), on top of the workflow's own success criteria:
$ suspect test run flows.arazzo.yaml --base-url http://localhost:8080 --input petName=Rex
$ suspect test run tests/ --junit out/contract.xml # every suite under tests/, one gate
$ suspect test load profile.load.yaml
$ suspect traffic gateway api.yaml -p 9000 --mode record --upstream http://staging:80 --cassette rec.scj
$ suspect test run flows.arazzo.yaml --cassette rec.scj # offline, from the recording
$ suspect traffic gateway api.yaml -p 8080 --mode mock --enforce # a mock that holds consumers to the contractSee contract testing and its runnable
example in examples/contract-testing/,
load testing with
examples/load/, and the gateway guide.
suspect check every check the editor runs; exit 1 on errors
suspect validate check, structure and semantics only
suspect lint check, lint, markdown and TypeScript rules only
suspect fmt | bundle | upgrade | stats
suspect overlay apply | explain | diff
suspect diff structural | breaking | impact | sdk | routes
suspect gen docs | sdk | stubs | contract | terraform | cli | mcp
template | session | bridge | profiles | admission
suspect test run | stateful | fuzz | load | replay
suspect traffic gateway | drift | har
suspect release plan | publish | workflow
suspect project init | check | build
suspect ci every project under a root, as one gate
suspect why trace a validation failure to its origin
suspect rules check | new | bench (TypeScript rules on Bun)
suspect config | auth | acquire | watch | lsp
suspect dev bench | evidence
Every command and flag is in the generated
command reference. Exit codes are shared: 0 clean, 1
findings or failed checks, 2 usage or environment error, 130
interrupted.
- Documentation index: guides, references, per-language SDK notes and design records.
- Guides: linting, editors, contract testing, gateway, docs generation, SDK generation, load testing.
- Reference: CLI, diagnostic codes, configuration, environment variables, LSP features, SDK features.
- How suspect compares with vacuum and Telescope.
- Plans: the toolchain unification proposals.
Earlier plans, including the
feature roadmap, are kept in
docs/internal/. - CONTRIBUTING.md: development setup, the crate map and
cargo xtask ci.
Licensed under either of Apache License, Version 2.0 or MIT, at your option. See CONTRIBUTING.md for development setup.