typespec-rust-emitter 0.6.0 → 0.8.0

package/QWEN.md

@@ -1,292 +0,0 @@
-# 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` - core codegen logic
-- **Package**: `typespec-rust-emitter` v0.3.0
-
-## Directory Structure
-
-```
-typespec-emitter/
-├── src/
-│   ├── emitter.ts          # MAIN: TypeSpec→Rust code generation
-│   ├── index.ts            # Exports ($onEmit, $rustDerive, $rustDerives, $rustAttr, $rustAttrs)
-│   ├── lib.ts              # TypeSpec library definition
-│   ├── lib.tsp             # Decorator declarations
-│   └── testing/            # Test utilities
-├── test/
-│   ├── hello.test.ts       # Unit 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 (models & enums, e.g., `sqlx::FromRow`, `sqlx::Type`)     |
-| `@rustDerives("...", "...")` | Adds multiple custom derives (models & enums)                                |
-| `@rustAttr("...")`           | Adds custom Rust attribute (models & enums, e.g., `sqlx(type_name = "...")`) |
-| `@rustAttrs("...", "...")`   | Adds multiple custom attributes (models & enums)                             |
-| `@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 accept individual parameters (path params, body) directly
-- Path params extracted with `Path<T>`
-- Body extracted with `Json<T>`
-- Protected routes (`@useAuth`) receive `claims: Self::Claims` via `Extension<Self::Claims>`
-- Extractor order: `State` → `Extension` → `Path` → `Json`
-- `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.4.0 - Individual Parameters Instead of Request Structs
-
-**Breaking Changes**:
-
-- Server trait methods now accept individual parameters instead of request structs
-  - `async fn subjects_create(&self, claims: Self::Claims, request: SubjectsCreateRequest)` → `async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody)`
-- Request structs (`SubjectsCreateRequest`, etc.) are no longer generated
-- Handler extractor order follows axum conventions: `State` → `Extension` → `Path` → `Json`
-
-**Benefits**:
-
-- Cleaner server trait API - no boilerplate request structs
-- Direct parameter access in handler implementations
-- Follows axum best practices for extractor ordering
-- Better IDE autocomplete for handler parameters
-
-**Example**:
-
-```typespec
-@post
-@route("/groups/{groupId}/subjects")
-op create(@path groupId: int64, @body body: CreateSubjectBody): Subject;
-```
-
-```rust
-// Server trait
-async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody) -> Result<...>;
-
-// Handler
-Extension(claims): Extension<S::Claims>,
-Path(group_id): Path<i64>,
-Json(payload): Json<CreateSubjectBody>
-let result = service.subjects_create(claims, group_id, payload).await;
-```
-
-### 2026-03-27: v0.3.0 - Custom Attributes & Enum Derives
-
-**New Features**:
-
-- `@rustAttr` / `@rustAttrs` decorators for custom Rust attributes (models & enums)
-- `@rustDerive` / `@rustDerives` now work on enums (previously models only)
-- Attributes render after `#[derive(...)]` for proper Rust syntax
-
-**Example**:
-
-```typespec
-@rustDerive("sqlx::Type")
-@rustAttr("sqlx(type_name = \"study_status\")")
-enum StudyStatus { Starting, Paused }
-```
-
-```rust
-#[derive(..., sqlx::Type)]
-#[sqlx(type_name = "study_status")]
-pub enum StudyStatus { ... }
-```
-
-### 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