WeaveFFI Roadmap

This roadmap tracks high-level goals for WeaveFFI. The project generates multi-language bindings from an API definition (YAML, JSON, or TOML), producing a stable C ABI contract consumed by language-specific wrappers.

Crate structure

What works today

• CLI with commands: generate, new, validate, extract, lint, diff, doctor, completions, schema-version
• IR parsing from YAML, JSON, and TOML with validation (name collisions, reserved keywords, unsupported shapes)
• Code generators for C, C++, Swift, Android, Node.js, WASM, Python, .NET, Dart, Go, and Ruby targets
• Rich type system: primitives, strings, bytes, handles, typed handles, structs, enums, optionals, lists, maps, iterators, callbacks
• Annotated Rust extraction — derive/proc-macro input as an alternative to hand-written YAML
• Incremental codegen with content-hash caching to skip unchanged files
• Generator configuration via TOML config file with per-target options
• Inline generator config via [generators.<target>] sections in IDL files
• Template engine — Tera-based user-overridable code templates loaded from a templates/ directory
• Pre/post hooks — run arbitrary scripts before and after code generation
• Scaffolding — --scaffold emits Rust extern "C" stubs for the API (sync and async)
• Inline helpers — error types and memory management utilities generated into each package
• Samples demonstrating end-to-end usage (calculator, contacts, inventory, async-demo, events)
• C ABI layer with error struct, string/bytes free functions, error domains, typed handles, and callback convention
• Validation warnings — --warn and lint command for non-fatal diagnostics
• Diff mode — compare generated output against existing files
• Shell completions — weaveffi completions <shell> for bash, zsh, fish, PowerShell
• Schema versioning — IR version field with schema-version for querying
• Async IR model — async functions with completion callback convention and cancellation support
• Advanced IR features — sub-modules, builder pattern, deprecated/since annotations, mutable params, default field values, borrowed types

Completed

• Usable CLI that reads a YAML IR, validates it, and generates bindings for all five original targets (C, Swift, Android, Node, WASM)
• Calculator sample and mdBook documentation site
• C ABI layer with error struct, string/bytes free functions, and handle convention
• Extended IR: structs, enums, optional types, arrays/slices, and maps
• Richer string and byte-buffer handling
• Packaging improvements (SwiftPM, Gradle, npm scaffolds)
• Annotated Rust crate extraction (weaveffi extract) as an alternative to hand-written YAML
• Improved diagnostics, validation warnings, and weaveffi lint command
• Incremental codegen with content-hash caching
• Generator configuration via TOML config file
• DX polish: --dry-run, --quiet, --verbose, diff command, improved doctor
• Python target (ctypes + .pyi type stubs + pip-installable package)
• .NET target (P/Invoke + .csproj + .nuspec)
• Inline generated helpers per target (error types, memory wrappers)
• WASM generator rewritten to be API-driven (JS wrappers + .d.ts)
• Inventory sample demonstrating multi-module and cross-type features
• Publishing to crates.io with automated semantic-release pipeline
• C++ target (RAII wrappers, std::string/std::vector/std::optional/std::unordered_map, CMakeLists.txt, exception-based errors, configurable namespace/header/standard)
• Dart target (dart:ffi bindings, enum generation, pubspec.yaml, null-safe code, configurable package name)
• Go target (CGo bindings, Go error pattern, go.mod, idiomatic naming, configurable module path)
• Ruby target (FFI gem bindings, struct class wrappers, gemspec, enum modules, configurable module/gem namespace)
• Template engine (Tera) with user-overridable templates and template directory discovery
• Pre-generation and post-generation hook commands
• Inline [generators.<target>] sections in IDL files for per-target configuration
• IR schema version field
• Shell auto-completions (weaveffi completions <shell> for bash, zsh, fish, PowerShell)
• Improved weaveffi new with full project scaffold (Cargo.toml, lib.rs, IDL, README)
• Typed handles (handle<Name>) replacing raw u64 for type-safe handle usage
• Benchmarking infrastructure (criterion) for codegen throughput
• Async IR model and C ABI async convention (completion callbacks with context pointers)
• Callback and listener patterns in the IR (register/unregister function pairs)
• Iterator type in the IR for streaming/sequence patterns
• Nested sub-module support in the IR
• Builder pattern support for struct construction
• Versioned API evolution: deprecated/since annotations, default field values
• Borrowed types (&str, &[u8]) for zero-copy parameter passing
• Mutable parameter annotations for safer codegen
• Async-demo and events samples demonstrating callbacks, listeners, and iterators
• Cross-module type references (struct in one module used as param in another)
• WASM generator aligned with the C ABI error model (out_err parameter handling in generated JS)
• Node N-API addon stub bodies completed with functional glue
• End-to-end integration tests for JSON and TOML input formats
• Generator edge-case coverage (deeply nested optionals, maps of lists, enum-keyed maps)
• Zero-copy string and byte-buffer passing (borrowed slices across the ABI boundary)
• Arena/pool allocation patterns for batch handle creation and destruction
• IR parsing and validation profiling and optimization
• Generated code memory safety audit (double-free, use-after-free, null pointer paths)
• Swift async/await mapping for async functions
• Kotlin coroutine (suspend fun) mapping for async functions
• Node.js Promise mapping for async functions
• Python asyncio mapping for async functions
• .NET Task<T> / async mapping for async functions
• Cancellation token support for long-running async operations
• Full cross-platform CI (Windows added to the test matrix)
• Security audit of all generated code patterns (memory safety, input validation)

Future releases

Dart Flutter integration

• Flutter plugin scaffold with platform channel integration

Documentation and benchmarks

• Benchmark results published on documentation site
• Per-target tutorials for C, C++, Dart, Go, Ruby, WASM, and .NET
• Cookbook recipes for common integration patterns

Design principle: standalone generated packages

Generated packages should be fully self-contained and publishable to their native ecosystem (npm, CocoaPods, Maven Central, PyPI, NuGet, pub.dev, etc.) without requiring consumers to install WeaveFFI tooling, runtimes, or support packages. WeaveFFI is a build-time tool for library authors — end users should never need to know it exists. Any helper code (error types, memory management utilities) is generated inline into each package rather than pulled from a shared runtime dependency.

Non-goals (for now)

• Full RPC / IPC framework: WeaveFFI generates in-process FFI bindings, not network protocols. gRPC, Cap’n Proto, or similar tools are better suited for cross-process communication.
• Automatic Rust implementation: WeaveFFI generates the consumer side (bindings). The library author still writes the Rust (or C) implementation behind the ABI.
• GUI framework bindings: Complex GUI toolkits with deep object hierarchies and inheritance are out of scope. WeaveFFI targets function-oriented APIs with flat or moderately nested data types.