typespec-rust-emitter 0.1.0 → 0.2.0

package/.qwen/settings.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(just *)",
+      "Bash(npm run *)",
+      "Bash(npm test)",
+      "Bash(cargo check)"
+    ]
+  },
+  "$version": 3
+}

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-27
+
+### Changed
+
+- **Breaking**: Server trait now uses associated type instead of generic parameter
+  - `pub trait Server<Claims>` → `pub trait Server` with `type Claims: Send + Sync + 'static`
+  - Users must now define their own `Claims` type instead of using the generated one
+- **Breaking**: `create_router` signature changed
+  - Now accepts middleware function: `create_router<S, M>(service: S, middleware: M)`
+  - Middleware type: `FnOnce(Router<S>) -> Router<S>`
+  - Protected routes wrapped with: `middleware(protected)`
+- Router now applies `.with_state(service)` once at the end instead of per-route
+- Removed generated `Claims` struct from `types.rs`
+
+### Added
+
+- Demo server implementation in `example/output-rust/src/main.rs`
+- Full server trait documentation in README.md
+
+### Benefits
+
+- Cleaner API - Claims type defined by user, not generated
+- Flexible middleware - any function matching the trait bound
+- No duplicate `.with_state(service.clone())` calls
+- Better separation of concerns - auth logic owned by user
+
+## [0.1.0] - 2026-03-27
+
+### Added
+
+- Initial release
+- TypeSpec to Rust code generation for:
+  - Models → `pub struct` with serde derives
+  - Enums → `pub enum` with serde rename
+  - Unions → `Option<T>` for nullable types
+  - Scalars → `pub type` or `pub struct` with pattern validation
+  - Error models → `thiserror::Error` derive
+  - Custom derives via `@rustDerive` and `@rustDerives` decorators
+- Server trait generation for axum HTTP operations
+- Support for `@useAuth` decorator to mark protected routes
+- Type mappings for common TypeSpec types and formats

package/DEV.md

@@ -0,0 +1,81 @@
+# TypeSpec Rust Emitter - LLM Context
+
+## Purpose
+
+TypeSpec emitter that generates idiomatic Rust code (structs, enums, server traits) from TypeSpec specifications.
+
+## Key Paths
+
+| Path                                 | Purpose                                                 |
+| ------------------------------------ | ------------------------------------------------------- |
+| `src/emitter.ts`                     | Main emitter logic (1464 lines) - TypeSpec→Rust codegen |
+| `src/lib.tsp`                        | Decorator declarations (`@rustDerive`, `@rustDerives`)  |
+| `test/hello.test.ts`                 | Unit tests using `emit()` helper                        |
+| `example/lib/learning/`              | Demo TypeSpec models & operations                       |
+| `example/output-rust/src/generated/` | Generated Rust output                                   |
+| `oas3-gen/crates/oas3-gen/`          | Reference template for codegen patterns                 |
+
+## Commands (Run After Every Change)
+
+```bash
+just build      # npm run build - Compile TypeScript
+just test       # npm test - Run unit tests
+just compile    # tsp compile example → generates Rust code
+just check-rust # cargo check - Verify Rust compiles
+```
+
+## Type Mappings
+
+| TypeSpec               | Rust                    |
+| ---------------------- | ----------------------- |
+| `string`               | `String`                |
+| `int32/64`             | `i32/i64`               |
+| `T \| null`            | `Option<T>`             |
+| `T[]`                  | `Vec<T>`                |
+| `Record<T>`            | `HashMap<String, T>`    |
+| `@format("uuid")`      | `uuid::Uuid`            |
+| `@format("date-time")` | `chrono::DateTime<Utc>` |
+
+## Architecture
+
+1. `navigateProgram()` walks TypeSpec AST
+2. Collects models, enums, operations
+3. Processes decorators
+4. Generates Rust code via string templates
+5. Emits to `example/output-rust/src/generated/`
+
+## Server Trait Generation
+
+- Generates `Server<Claims>` trait with async methods per operation
+- Handler functions: `pub async fn {op}_handler<S, Claims>(...)`
+- All handlers use `<S, Claims>` generics (even public routes)
+- Protected routes (`@useAuth`) receive `claims: Claims` parameter
+- Router splits public/protected routes, merges at end
+
+## Test Pattern
+
+```typescript
+import { emit } from "./test-host.js";
+const results = await emit(`model User { name: string; }`);
+const output = results["types.rs"];
+strictEqual(output.includes("pub struct User"), true);
+```
+
+## Recent Fix (2026-03-27)
+
+All handler functions now use `<S, Claims>` generics uniformly. Public routes include `Claims: Send + Sync + Clone + 'static` bound even without using Claims, because Server trait requires it.
+
+## Rules
+
+1. Always run full cycle: `build → test → compile → check-rust`
+2. TypeScript strict mode enabled - no implicit any
+3. Match existing code patterns in `src/emitter.ts`
+4. Add tests for new features
+5. Generated Rust must compile
+
+## Todo
+
+- [ ] More server trait test coverage
+- [ ] Integration tests with Rust compilation
+- [ ] Expand scalar format mappings
+- [ ] Full working Rust server example

package/QWEN.md

@@ -0,0 +1,216 @@
+# QWEN.md - Project Context
+
+## Project Overview
+
+**TypeSpec Rust Emitter** - A TypeScript-based code generator that converts TypeSpec specifications into idiomatic Rust code.
+
+- **Type**: TypeScript/Node.js project (TypeSpec emitter)
+- **Output**: Generates Rust structs, enums, server traits with serde, thiserror, axum support
+- **Main Entry**: `src/emitter.ts` (1450 lines) - core codegen logic
+- **Package**: `typespec-rust-emitter` v0.2.0
+
+## Directory Structure
+
+```
+typespec-emitter/
+├── src/
+│   ├── emitter.ts          # MAIN: TypeSpec→Rust code generation
+│   ├── index.ts            # Exports ($onEmit, $rustDerive, $rustDerives)
+│   ├── lib.ts              # TypeSpec library definition
+│   ├── lib.tsp             # Decorator declarations
+│   └── testing/            # Test utilities
+├── test/
+│   ├── hello.test.ts       # Unit tests (11 tests)
+│   └── test-host.ts        # Test infrastructure (emit() helper)
+├── example/
+│   ├── main.tsp            # Demo TypeSpec entry
+│   ├── lib/learning/       # Demo models & operations
+│   ├── tspconfig.yaml      # Emitter configuration
+│   └── output-rust/        # Generated Rust crate
+├── oas3-gen/               # Reference template repo
+├── dist/                   # Compiled TypeScript output
+├── package.json            # Dependencies & scripts
+├── tsconfig.json           # TypeScript config (strict mode)
+└── justfile                # Build automation
+```
+
+## Build & Run Commands
+
+### Primary Workflow (Run After Every Change)
+```bash
+just build      # Compile TypeScript (npm run build)
+just test       # Run unit tests (npm test)
+just compile    # Generate Rust code from example
+just check-rust # Verify Rust compiles (cargo check)
+```
+
+### Individual Commands
+```bash
+# Development
+npm run build       # tsc compile
+npm run watch       # Watch mode
+npm run lint        # ESLint check
+npm run lint:fix    # Auto-fix lint
+npm run format      # Prettier format
+npm run format:check
+
+# Full pipeline
+just install        # npm install (root + example)
+just publish        # build + npm publish
+```
+
+## Type Mappings (TypeSpec → Rust)
+
+| TypeSpec | Rust |
+|----------|------|
+| `string` | `String` |
+| `int8/16/32/64` | `i8/i16/i32/i64` |
+| `uint8/16/32/64` | `u8/u16/u32/u64` |
+| `float32/64` | `f32/f64` |
+| `boolean` | `bool` |
+| `bytes` | `Vec<u8>` |
+| `T[]` | `Vec<T>` |
+| `Record<T>` | `HashMap<String, T>` |
+| `T \| null` | `Option<T>` |
+
+### Format Mappings
+| `@format()` | Rust Type |
+|-------------|-----------|
+| `"uuid"` | `uuid::Uuid` |
+| `"date"` | `chrono::NaiveDate` |
+| `"time"` | `chrono::NaiveTime` |
+| `"date-time"` | `chrono::DateTime<Utc>` |
+
+## Decorators
+
+| Decorator | Effect |
+|-----------|--------|
+| `@error` | Adds `thiserror::Error` derive + `#[error("{code}: {message}")]` |
+| `@pattern("regex")` | Generates `TryFrom<String>` with regex validation |
+| `@rustDerive("...")` | Adds custom derive (e.g., `sqlx::FromRow`) |
+| `@rustDerives("...", "...")` | Adds multiple custom derives |
+| `@doc("...")` | Generates `///` doc comments |
+| `@useAuth(BearerAuth)` | Marks operation as protected (adds `Claims` param) |
+| `@maxLength(n)` | Documentation only |
+
+## Output Files
+
+### types.rs
+- All models → `pub struct` with serde derives
+- Enums → `pub enum` with serde rename
+- Unions → `Option<T>` for nullable, or sum types
+- Scalars → `pub type` or `pub struct` (if pattern validation)
+
+### server.rs
+- `Server` trait with `type Claims` associated type
+- Request structs per operation
+- Response enums with status code variants
+- `create_router<S, M>(service: S, middleware: M)` function with axum routes
+
+## Key Implementation Details
+
+### emitter.ts Architecture
+1. `navigateProgram()` - Walks TypeSpec AST
+2. Collects: models, enums, unions, scalars, operations
+3. Processes decorators (`@error`, `@pattern`, `@rustDerive`)
+4. Generates Rust via string templates
+5. Emits files to configured output directory
+
+### Server Trait Generation
+- Generates `Server` trait with `type Claims: Send + Sync + 'static` associated type
+- Handler functions: `pub async fn {op}_handler<S>(...)` with `<S>` generics only
+- Protected routes (`@useAuth`) receive `claims: Self::Claims` via `Extension<Self::Claims>`
+- Public routes don't require claims
+- `create_router<S, M>(service: S, middleware: M)` accepts middleware function
+- Middleware wraps protected routes: `middleware(protected)`
+- Router merges public/protected, applies `.with_state(service)` once at end
+
+### Test Pattern
+```typescript
+import { emit } from "./test-host.js";
+const results = await emit(`model User { name: string; }`);
+const output = results["types.rs"];
+strictEqual(output.includes("pub struct User"), true);
+```
+
+## Dependencies
+
+### Peer (Required)
+- `@typespec/compiler` >=1.0.0
+- `@typespec/emitter-framework` ^0.17.0
+
+### Dev
+- `typescript` ^5.3.3
+- `eslint` ^9.15.0
+- `prettier` ^3.3.3
+
+### Generated Rust (example/output-rust/Cargo.toml)
+```toml
+serde = { version = "1.0", features = ["derive"] }
+thiserror = "2.0"
+uuid = { version = "1.23", features = ["serde"] }
+chrono = { version = "0.4", features = ["serde"] }
+regex = "1.12"
+sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "derive"] }
+axum = "0.8"
+eyre = "0.6"
+async-trait = "0.1"
+tokio = { version = "1.50", features = ["full"] }
+```
+
+## Configuration Files
+
+### tspconfig.yaml
+```yaml
+emit:
+  - "@typespec/openapi3"
+  - "typespec-rust-emitter"
+options:
+  "typespec-rust-emitter":
+    emitter-output-dir: "{output-dir}/../output-rust/src/generated"
+```
+
+### tsconfig.json
+- Target: ES2022
+- Module: NodeNext
+- Strict: true
+- Root/Out: `.` → `dist`
+
+## Development Conventions
+
+1. **TypeScript**: Strict mode, ES2022, NodeNext modules
+2. **Testing**: Node.js built-in test runner (`node:test`)
+3. **Formatting**: Prettier (yaml config)
+4. **Linting**: ESLint + typescript-eslint
+5. **Code Style**: Match existing patterns in `src/emitter.ts`
+
+## Rules
+
+1. Always run full cycle after changes: `build → test → compile → check-rust`
+2. Add tests for new features in `test/hello.test.ts`
+3. Generated Rust must compile (verify with `just check-rust`)
+4. Reference `oas3-gen/` for advanced codegen patterns
+5. No implicit any (strict TypeScript)
+
+## Recent Changes
+
+### 2026-03-27: v0.2.0 - Server Trait Refactoring
+
+**Changes**:
+- `pub trait Server<Claims>` → `pub trait Server` with `type Claims` associated type
+- Removed generated `Claims` struct from `types.rs` (users define their own)
+- `create_router<S, M>(service: S, middleware: M)` now accepts middleware function
+- Middleware wraps protected routes: `middleware(protected)`
+- Single `.with_state(service)` call at end of router creation
+
+**Benefits**:
+- Cleaner API - Claims type defined by user, not generated
+- Flexible middleware - any function `FnOnce(Router<S>) -> Router<S>`
+- No duplicate `.with_state(service.clone())` calls
+
+## TODO
+
+- [ ] More server trait test coverage
+- [ ] Integration tests with Rust compilation
+- [ ] Expand scalar format mappings (more chrono types)
+- [ ] Support additional HTTP decorators

package/README.md

@@ -1,4 +1,4 @@
-Authored by [opencode](https://opencode.ai)
+Authored by [opencode](https://opencode.ai) & Qwen
 
 ---
 
@@ -19,6 +19,7 @@ A TypeSpec emitter that generates idiomatic Rust types and structs from TypeSpec
 - **Error Models**: Generates `thiserror::Error` derive with `#[error(...)]` attributes
 - **Pattern Validation**: Supports `@pattern` decorators with `TryFrom<String>` validation
 - **Custom Derives**: Add arbitrary Rust derive macros via `@rustDerive` decorator
+- **Server Trait**: Generates axum server trait and router from HTTP operations
 
 ## Installation
 
@@ -36,8 +37,6 @@ npm install @typespec/compiler @typespec/emitter-framework
 
 ## Usage
 
-## Usage
-
 ### Basic Model
 
 ```typespec
@@ -179,6 +178,136 @@ pub struct GroupStatistics {
 }
 ```
 
+## Server Trait Generation
+
+The emitter can generate a complete axum server trait and router from TypeSpec HTTP operations.
+
+### Example TypeSpec
+
+```typespec
+@route("/groups")
+namespace Groups {
+  @get
+  @route("")
+  op list(): Group[];
+
+  @post
+  @route("")
+  @useAuth(BearerAuth)
+  op create(@body body: CreateGroupBody): Group;
+
+  @get
+  @route("/{id}")
+  op getById(@path id: int64): Group;
+}
+```
+
+### Generated Server Trait
+
+```rust
+#[async_trait]
+pub trait Server: Send + Sync {
+    type Claims: Send + Sync + 'static;
+
+    async fn groups_list(&self, request: GroupsListRequest) -> Result<GroupsListResponse>;
+    async fn groups_create(&self, claims: Self::Claims, request: GroupsCreateRequest) -> Result<GroupsCreateResponse>;
+    async fn groups_get_by_id(&self, request: GroupsGetByIdRequest) -> Result<GroupsGetByIdResponse>;
+}
+```
+
+### Implementing the Server
+
+```rust
+#[derive(Clone)]
+pub struct AppState {
+    pub db: Arc<SqlitePool>,
+}
+
+pub struct MyServer {
+    state: AppState,
+}
+
+#[async_trait::async_trait]
+impl Server for MyServer {
+    type Claims = Claims; // Your custom claims type
+
+    async fn groups_list(
+        &self,
+        _request: GroupsListRequest,
+    ) -> eyre::Result<GroupsListResponse> {
+        let groups = sqlx::query_as::<_, Group>("SELECT * FROM groups")
+            .fetch_all(&self.state.db)
+            .await?;
+        Ok(GroupsListResponse::Ok(Json(groups)))
+    }
+
+    async fn groups_create(
+        &self,
+        claims: Self::Claims,
+        request: GroupsCreateRequest,
+    ) -> eyre::Result<GroupsCreateResponse> {
+        // claims.sub contains the authenticated user ID
+        let group = sqlx::query_as::<_, Group>(
+            "INSERT INTO groups (name, owner_id) VALUES ($1, $2) RETURNING *"
+        )
+        .bind(&request.body.name)
+        .bind(&claims.sub)
+        .fetch_one(&self.state.db)
+        .await?;
+        Ok(GroupsCreateResponse::Created(Json(group)))
+    }
+
+    // ... implement other methods
+}
+```
+
+### Creating the Router
+
+```rust
+// Define your claims type
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Claims {
+    pub sub: String,
+    pub exp: usize,
+}
+
+// Create auth middleware
+async fn auth_middleware(
+    Extension(claims): Extension<Claims>,
+    request: Request<axum::body::Body>,
+    next: Next,
+) -> Result<Response, StatusCode> {
+    // Validate claims (e.g., check expiration)
+    if claims.exp < (chrono::Utc::now().timestamp() as usize) {
+        return Err(StatusCode::UNAUTHORIZED);
+    }
+    Ok(next.run(request).await)
+}
+
+// Apply middleware to protected routes
+fn with_auth<S>(router: Router<S>) -> Router<S>
+where
+    S: Server + Clone + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+{
+    router.layer(axum::middleware::from_fn(auth_middleware))
+}
+
+// Create the router
+let server = MyServer::new(state);
+let router = create_router(server, with_auth);
+axum::serve(listener, router).await?;
+```
+
+### Protected Routes
+
+Operations decorated with `@useAuth` will:
+
+- Receive `claims: Self::Claims` as the first parameter
+- Be wrapped with the middleware passed to `create_router`
+
+Public routes do not receive claims and are not wrapped with auth middleware.
+
 ## Type Mappings
 
 | TypeSpec Type    | Rust Type                                   |
@@ -193,6 +322,26 @@ pub struct GroupStatistics {
 | `Record<string>` | `std::collections::HashMap<String, String>` |
 | `T \| null`      | `Option<T>`                                 |
 
+### Format Mappings
+
+| `@format()`   | Rust Type               |
+| ------------- | ----------------------- |
+| `"uuid"`      | `uuid::Uuid`            |
+| `"date"`      | `chrono::NaiveDate`     |
+| `"time"`      | `chrono::NaiveTime`     |
+| `"date-time"` | `chrono::DateTime<Utc>` |
+
+## Decorators
+
+| Decorator                    | Description                                           |
+| ---------------------------- | ----------------------------------------------------- |
+| `@error`                     | Adds `thiserror::Error` derive with error message     |
+| `@pattern("regex")`          | Generates `TryFrom<String>` with regex validation     |
+| `@rustDerive("...")`         | Adds a custom derive macro (e.g., `sqlx::FromRow`)    |
+| `@rustDerives("...", "...")` | Adds multiple custom derive macros                    |
+| `@doc("...")`                | Generates `///` doc comments                          |
+| `@useAuth(AuthType)`         | Marks operation as protected, adds `Claims` parameter |
+
 ## Building
 
 ```bash