Skip to content
asamartsPublic

About

A WIT-first contract compiler: plain Rust types and traits and a protobuf schema with stable field numbers from one WIT package.

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

witforge

CI crates.io docs API docs MSRV

Compile one hand-written WIT contract into the runtime-independent artifacts its consumers need.

witforge checks a deliberately portable WIT subset, locks protobuf field and method numbers, and generates stable Rust, protobuf, JSON Schema, glue, compatibility reports, and adapters between contract versions.

Current release: 0.5.0. The 1.0 release remains intentionally gated on successful independent consumer validation.

Outputs

Output Purpose
Plain Rust Owned structs, enums, interface traits, world metadata, and optional Serde derives
Protobuf Messages and method IDs with append-only numbers from wire.lock
JSON Schema Draft 7 definitions for WIT-shaped values
Rust glue Checked conversion between plain Rust and prost-generated protobuf types
Version adapters Old-to-new and new-to-old conversion between adjacent contract versions
Diff and diagnostics Human, JSON, and SARIF compatibility/change reports

When it fits

Use witforge when:

  • hand-written WIT is the source of truth;
  • the callable contract is pure, synchronous, and value-oriented;
  • native Rust and out-of-process implementations share the same values;
  • protobuf identity must remain stable across releases;
  • generated output is committed and checked in CI;
  • contract changes need explicit compatibility review.

Use wit-bindgen and a Component Model runtime directly when you only need guest and host Component Model bindings.

witforge does not load components, generate protobuf services, own process framing, or define callbacks, retries, capabilities, resource limits, discovery, or failure policy. Direct Go source generation is not available yet; non-Rust consumers use the emitted protobuf schema, their normal language toolchain, and the documented WIT decode profile.

Install

cargo install witforge-cli --version 0.5.0 --locked
witforge --version

Prebuilt checksum files and archives are also published for Linux x86_64, macOS Intel and Apple silicon, and Windows x86_64.

Five-minute example

Create wit/v0.1/contract.wit:

package example:checker@0.1.0;

interface api {
  record request {
    text: string,
  }

  record diagnostic {
    start: u32,
    end: u32,
    message: string,
  }

  check: func(input: request) -> list<diagnostic>;
}

world plugin {
  export api;
}

Lock and validate the first version:

witforge lock wit/v0.1 --first
witforge check wit/v0.1

Generate the projections:

witforge rust wit --out generated/rust
witforge proto wit --out generated/proto
witforge schema wit --out generated/schema
witforge glue wit --out generated/glue \
  --plain-root crate::plain \
  --proto-root crate::proto

Every generator supports --check, which writes nothing and fails when committed output differs.

What gets generated

For the WIT above, the generated Rust module contains ordinary owned values and a trait:

pub mod api {
    #[derive(Debug, Clone, PartialEq)]
    pub struct Request {
        pub text: ::std::string::String,
    }

    #[derive(Debug, Clone, PartialEq)]
    pub struct Diagnostic {
        pub start: u32,
        pub end: u32,
        pub message: ::std::string::String,
    }

    pub trait Api {
        fn check(&self, input: Request) -> ::std::vec::Vec<Diagnostic>;
    }
}

The same contract becomes protobuf messages and a locked method ID:

message ApiRequest {
  optional string text = 1;
}

message ApiDiagnostic {
  optional uint32 start = 1;
  optional uint32 end = 2;
  optional string message = 3;
}

message ApiCheckRequest {
  ApiRequest input = 1;
}

message ApiCheckResponse {
  repeated ApiDiagnostic result = 1;
}

enum ApiMethod {
  API_METHOD_UNSPECIFIED = 0;
  API_METHOD_CHECK = 1;
}

These excerpts are checked against current emitter output by the test suite, not hand-designed target APIs. The generated-output guide shows complete Rust, protobuf, JSON Schema, glue, and version-adapter examples with links to committed generated files.

For configuration, dependencies, evolution, and complete command sequences, continue with the documentation or the repository quickstart.

Evolve a contract

Keep each contract version in its own directory. Start a new minor as a copy of the previous version, lockfile included:

mkdir wit/v0.2
cp wit/v0.1/contract.wit wit/v0.1/wire.lock wit/v0.2/
# Edit wit/v0.2/contract.wit: set the package version to 0.2.0, then change the contract.
witforge lock wit/v0.2 --against wit/v0.1/wire.lock
witforge check wit/v0.2 --against wit/v0.1/wire.lock
witforge diff wit/v0.1 wit/v0.2

Released WIT, lockfiles, dependency packages, and generated per-version Rust modules are immutable. Create a new version directory instead of editing a released one.

Add --check when CI must reject source- or generated-API-breaking changes. The evolved repository example intentionally adds defaultable fields, so its adapters can convert old values even though diff --check reports the source/API change.

CI

Pin the Action to the same release used locally:

- uses: asamarts/witforge@v0.5.0
  with:
    check: wit/v0.2
    config: witforge.toml
    generators: rust,proto,schema,glue
- run: witforge diff wit/v0.1 wit/v0.2

The Action downloads the matching checksum-verified release binary, leaves witforge on PATH, and runs the configured generators with --check. The second step prints the contract diff. Add --check to it to fail the job on a wire-, source-, or generated-API-breaking change, which includes an added record field. The Action also has diff-old, diff-new, and diff-check inputs; releases up to v0.5.0 ignore them. See the CI guide.

Important JSON boundary

Rust Serde and JSON Schema project the same WIT values, but they do not define one identical JSON wire format. Rust fields are snake_case; JSON Schema preserves WIT spelling, normally kebab-case. WIT option<T> permits null but does not make a schema property omittable.

Read JSON projections before choosing a JSON boundary.

Documentation and examples

The first consumer is the alint plugin contract. Task-level planning and closure evidence live under aplan/; ROADMAP.md is the narrative sequence.

Security

Report vulnerabilities through GitHub private vulnerability reporting, not a public issue. See SECURITY.md.

License

Licensed under either Apache-2.0 or MIT, at your option.

About

A WIT-first contract compiler: plain Rust types and traits and a protobuf schema with stable field numbers from one WIT package.

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages