typespec-rust-emitter 0.7.0 → 0.9.0

package/.qwen/settings.json

@@ -1,4 +1,5 @@
 {
+  "$version": 3,
   "permissions": {
     "allow": [
       "Bash(just *)",
@@ -7,5 +8,5 @@
       "Bash(cargo check)"
     ]
   },
-  "$version": 3
-}
+  "context.fileName": "AGENTS.md"
+}

package/AGENTS.md

@@ -0,0 +1,167 @@
+# TypeSpec Rust Emitter - Agent Guidelines
+
+## Overview
+
+TypeSpec emitter that generates idiomatic Rust code (structs, enums, server traits) from TypeSpec specifications.
+
+## Build, Lint, and Test Commands
+
+### Standard Commands
+
+```bash
+# Build TypeScript
+npm run build           # or: just build
+
+# Run tests
+npm test                # or: just test
+node --test 'dist/test/**/*.test.js'
+
+# Run a single test file
+node --test 'dist/test/hello.test.js'
+
+# Run a specific test
+node --test 'dist/test/hello.test.js' --test-name-pattern="emits model"
+
+# Lint
+npm run lint            # Check linting
+npm run lint:fix        # Auto-fix linting issues
+
+# Format code
+npm run format          # Format all files
+npm run format:check    # Check formatting without changes
+
+# Compile TypeSpec to Rust
+just compile            # Runs: cd example && tsp compile .
+
+# Verify generated Rust compiles
+just check-rust         # Runs: cd example/output-rust && cargo check
+```
+
+### Full Development Cycle
+
+After every change, run this sequence:
+
+```bash
+just build && npm test && just compile && just check-rust
+```
+
+## Project Structure
+
+| Path                                 | Purpose                                                  |
+| ------------------------------------ | -------------------------------------------------------- |
+| `src/emitter.ts`                     | Main emitter logic (~1500 lines) - TypeSpec→Rust codegen |
+| `src/lib.tsp`                        | Decorator declarations (`@rustDerive`, `@rustDerives`)   |
+| `src/lib.ts`                         | Decorator implementations                                |
+| `src/index.ts`                       | Public API exports                                       |
+| `src/testing/index.ts`               | Test utilities                                           |
+| `test/hello.test.ts`                 | Unit tests using `emit()` helper                         |
+| `test/test-host.ts`                  | Test host setup                                          |
+| `example/lib/`                       | Demo TypeSpec models & operations                        |
+| `example/output-rust/src/generated/` | Generated Rust output                                    |
+
+## Code Style
+
+### TypeScript
+
+- **Strict mode enabled** - No implicit `any`
+- **No `any` types** - Use `unknown` or proper generics instead
+- **Explicit return types** on public functions
+- **Interfaces over type aliases** for object shapes
+
+### Imports
+
+- Named imports from `@typespec/compiler` first, then external packages
+- Group imports: 1) `@typespec/*`, 2) external, 3) internal
+- Use `import type { X }` for type-only imports when appropriate
+
+### Formatting (Prettier)
+
+Configuration in `prettierrc.yaml`:
+
+- `printWidth: 120`
+- `trailingComma: "all"`
+- `arrowParens: always`
+- `endOfLine: lf`
+
+Use `npm run format` before committing.
+
+### Naming Conventions
+
+| Element                     | Convention | Example              |
+| --------------------------- | ---------- | -------------------- |
+| TypeScript functions        | camelCase  | `$rustDerive`        |
+| TypeScript types/interfaces | PascalCase | `RustEmitterOptions` |
+| Rust types                  | PascalCase | `pub struct User`    |
+| Rust functions/methods      | snake_case | `get_user_by_id`     |
+| Internal symbols            | camelCase  | `rustDeriveKey`      |
+
+### Type Mappings (TypeSpec → Rust)
+
+| TypeSpec               | Rust                    |
+| ---------------------- | ----------------------- |
+| `string`               | `String`                |
+| `int32/64`             | `i32/i64`               |
+| `float32/64`           | `f32/f64`               |
+| `boolean`              | `bool`                  |
+| `T \| null`            | `Option<T>`             |
+| `T[]`                  | `Vec<T>`                |
+| `Record<T>`            | `HashMap<String, T>`    |
+| `@format("uuid")`      | `uuid::Uuid`            |
+| `@format("date-time")` | `chrono::DateTime<Utc>` |
+
+## Error Handling
+
+- Use `context.program.reportDiagnostic()` for errors and warnings
+- Diagnostic codes should use kebab-case: `code: "rust-derive-invalid-target"`
+- Always specify `severity: "error"` or `"warning"`
+- Include `target: context.decoratorTarget` for location info
+
+## Testing 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);
+```
+
+## Server Trait Generation Rules
+
+1. Generates `Server<Claims>` trait with async methods per operation
+2. Handler functions: `pub async fn {op}_handler<S, Claims>(...)`
+3. All handlers use `<S, Claims>` generics (even public routes)
+4. Protected routes (`@useAuth`) receive `claims: Claims` parameter
+5. Router splits public/protected routes, merges at end
+6. Public routes include `Claims: Send + Sync + Clone + 'static` bound
+
+## 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/`
+
+## Linting
+
+ESLint config (`eslint.config.js`):
+
+- Uses `typescript-eslint` recommended rules
+- Ignores `dist/**` and `.temp/**`
+- Unused variables: warn with `_` prefix exception
+
+## Commit Message Style
+
+- Use clear, descriptive titles
+- Focus on "why" rather than "what"
+- Keep concise (1-2 sentences)
+- Example: "Fix handler generics for public routes without auth"
+
+## Checklist Before PR
+
+- [ ] Run full cycle: `just build && npm test && just compile && just check-rust`
+- [ ] Add tests for new features
+- [ ] Run `npm run lint` and `npm run format`
+- [ ] Generated Rust must compile with `cargo check`
+- [ ] No TypeScript errors

package/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.9.0] - 2026-03-31
+
+### Changed
+
+- **Error `IntoResponse` now uses dynamic status code from `code` field**: Instead of mapping status codes by error type name, errors now use `StatusCode::from_str(&self.code)` to determine the HTTP status code at runtime
+  - This allows defining any error type with custom codes without changing the emitter
+  - Falls back to `INTERNAL_SERVER_ERROR` if the code is not a valid HTTP status string
+
+### Example
+
+```rust
+// Error model with any code
+model CustomError {
+  code: string;      // e.g., "NOT_FOUND", "BAD_REQUEST", "MY_CUSTOM_CODE"
+  message: string;
+}
+
+impl IntoResponse for CustomError {
+    fn into_response(self) -> axum::response::Response {
+        (
+            StatusCode::from_str(&self.code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
+            Json(self),
+        )
+            .into_response()
+    }
+}
+```
+
+### Fixed
+
+- **Clippy warnings**: Enums and newtype structs with pattern validation now use `#[derive(Default)]` with `#[default]` attribute instead of manual `impl Default`, eliminating `clippy::derivable_impls` warnings
+
+### Internal
+
+- Added `use std::str::FromStr;` import to generated types.rs
+- Removed unused `getHttpStatusCodeForError()` function
+
+## [0.8.0] - 2026-03-30
+
+### Added
+
+- **axum IntoResponse implementation for error types**: Error models (`ApiError`, `NotFoundError`, `ValidationError`, `ConflictError`) now implement `axum::response::IntoResponse`
+  - Error types can be returned directly from axum handlers
+  - Status code mapping based on error name suffix:
+    - `*NotFoundError` → `404 NOT_FOUND`
+    - `*ValidationError` → `400 BAD_REQUEST`
+    - `*ConflictError` → `409 CONFLICT`
+    - Default → `500 INTERNAL_SERVER_ERROR`
+
+### Example
+
+```rust
+// Generated in types.rs
+impl IntoResponse for NotFoundError {
+    fn into_response(self) -> axum::response::Response {
+        (StatusCode::NOT_FOUND, Json(self)).into_response()
+    }
+}
+
+// In a handler, error types can be returned directly
+async fn get_item_handler<S>(/* ... */) -> impl IntoResponse {
+    // ...
+    NotFoundError { code: "NOT_FOUND".to_string(), message: "Item not found".to_string() }
+}
+```
+
 ## [0.7.0] - 2026-03-30
 
 ### Fixed

package/README.md

@@ -12,11 +12,11 @@ A TypeSpec emitter that generates idiomatic Rust types and structs from TypeSpec
 ## Features
 
 - **Models**: Converts TypeSpec models to Rust structs with serde derive macros
-- **Enums**: Supports both string and integer enums
+- **Enums**: Supports both string and integer enums with `Default` derive
 - **Unions**: Handles nullable types (`T | null` → `Option<T>`) and string literal unions
 - **Scalars**: Maps TypeSpec scalars to Rust equivalents with `@format` support
 - **Inheritance**: Supports model inheritance with `getAllProperties()`
-- **Error Models**: Generates `thiserror::Error` derive with `#[error(...)]` attributes
+- **Error Models**: Generates `thiserror::Error` derive with `#[error(...)]` attributes and `IntoResponse` impl for axum
 - **Pattern Validation**: Supports `@pattern` decorators with `TryFrom<String>` validation
 - **Custom Derives**: Add arbitrary Rust derive macros via `@rustDerive` decorator (models & enums)
 - **Custom Attributes**: Add arbitrary Rust attributes via `@rustAttr` decorator (models & enums)
@@ -78,8 +78,9 @@ enum Status {
 Generates:
 
 ```rust
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
 pub enum Status {
+    #[default]
     #[serde(rename = "active")]
     Active,
     #[serde(rename = "inactive")]
@@ -87,12 +88,6 @@ pub enum Status {
     #[serde(rename = "pending")]
     Pending,
 }
-
-impl Default for Status {
-    fn default() -> Self {
-        Status::Active
-    }
-}
 ```
 
 ### Error Model
@@ -116,8 +111,20 @@ pub struct ApiError {
     #[serde(rename = "message")]
     pub message: String,
 }
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> axum::response::Response {
+        (
+            StatusCode::from_str(&self.code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
+            Json(self),
+        )
+            .into_response()
+    }
+}
 ```
 
+Error codes are parsed dynamically, so any valid HTTP status code string (e.g., `"NOT_FOUND"`, `"BAD_REQUEST"`, `"418 I'M_A_TEAPOT"`) will work.
+
 ### UUID Format
 
 ```typespec
@@ -207,9 +214,10 @@ pub struct User {
     pub name: String,
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, sqlx::Type)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize, sqlx::Type)]
 #[sqlx(type_name = "study_status")]
 pub enum StudyStatus {
+    #[default]
     #[serde(rename = "Starting")]
     Starting,
     #[serde(rename = "Paused")]

package/dist/src/emitter.js

@@ -287,7 +287,7 @@ function getStatusCode(variant) {
 function getBodyFromResponse(variant, program, anonymousEnums) {
     if (variant.type.kind === "Model") {
         const model = variant.type;
-        for (const [propName, prop] of model.properties) {
+        for (const [_propName, prop] of model.properties) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const decorators = prop.decorators;
             let isBody = false;
@@ -414,9 +414,11 @@ function generateServerTrait(program, namespaceGroups, anonymousEnums) {
     const parts = [];
     parts.push(`use super::types::*;
 use async_trait::async_trait;
-use axum::{http::StatusCode, Json};
 use axum::extract::Path;
 use axum::Extension;
+use axum::http::StatusCode;
+use axum::response::IntoResponse;
+use axum::Json;
 use eyre::Result;
 
 #[async_trait]
@@ -610,8 +612,7 @@ where
     const methodImports = Array.from(usedMethods).sort().join(", ");
     const routerBody = buildRouterBody(publicRoutes, protectedRoutes);
     const parts = [];
-    parts.push(`use axum::response::IntoResponse;
-use axum::routing::{${methodImports}};
+    parts.push(`use axum::routing::{${methodImports}};
 use axum::Router;
 
 `);
@@ -870,17 +871,19 @@ function emitStringLiteralUnion(union) {
     const parts = [];
     const name = toPascalCase(union.name ?? "Value");
     const variants = Array.from(union.variants.values());
-    parts.push(`#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]\npub enum ${name} {`);
-    for (const variant of variants) {
-        const literalType = variant.type;
+    const defaultVariant = toRustVariantName(variants[0]?.type ? variants[0].type.value : "");
+    parts.push(`#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]\npub enum ${name} {`);
+    for (let i = 0; i < variants.length; i++) {
+        const literalType = variants[i].type;
         const variantName = toRustVariantName(literalType.value);
         const serdeValue = literalType.value;
+        if (i === 0) {
+            parts.push(`  #[default]`);
+        }
         parts.push(`  #[serde(rename = "${serdeValue}")]`);
         parts.push(`  ${variantName},`);
     }
     parts.push("}");
-    const defaultVariant = toRustVariantName(variants[0]?.type ? variants[0].type.value : "");
-    parts.push(`\n\nimpl Default for ${name} {\n  fn default() -> Self {\n    ${name}::${defaultVariant}\n  }\n}`);
     return parts.join("\n");
 }
 function emitModel(model, program, anonymousEnums) {
@@ -940,6 +943,18 @@ ${fields.join("\n")}
         parts.push(`pub struct ${name}`);
         parts.push("(());");
     }
+    if (isError && allProps.size > 0) {
+        parts.push(`
+impl IntoResponse for ${name} {
+    fn into_response(self) -> axum::response::Response {
+        (
+            StatusCode::from_str(&self.code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
+            Json(self),
+        )
+            .into_response()
+    }
+}`);
+    }
     return parts.join("\n");
 }
 function getAllProperties(model, _program) {
@@ -967,6 +982,7 @@ function emitEnum(enumType) {
         "PartialEq",
         "Eq",
         "Hash",
+        "Default",
         "serde::Serialize",
         "serde::Deserialize",
     ];
@@ -990,9 +1006,12 @@ function emitEnum(enumType) {
             parts.push(...attrLines);
         }
         parts.push(`pub enum ${name} {`);
-        for (const member of members) {
-            const variantName = toRustVariantName(member.name);
-            const serdeValue = member.value ?? member.name;
+        for (let i = 0; i < members.length; i++) {
+            const variantName = toRustVariantName(members[i].name);
+            const serdeValue = members[i].value ?? members[i].name;
+            if (i === 0) {
+                parts.push(`  #[default]`);
+            }
             parts.push(`  #[serde(rename = "${serdeValue}")]`);
             parts.push(`  ${variantName},`);
         }
@@ -1003,15 +1022,16 @@ function emitEnum(enumType) {
             parts.push(...attrLines);
         }
         parts.push(`pub enum ${name} {`);
-        for (const member of members) {
-            const variantName = toRustVariantName(member.name);
-            const enumValue = member.value ?? 0;
+        for (let i = 0; i < members.length; i++) {
+            const variantName = toRustVariantName(members[i].name);
+            const enumValue = members[i].value ?? 0;
+            if (i === 0) {
+                parts.push(`  #[default]`);
+            }
             parts.push(`  ${variantName} = ${enumValue},`);
         }
     }
     parts.push("}");
-    const defaultVariant = toRustVariantName(members[0]?.name ?? "");
-    parts.push(`\n\nimpl Default for ${name} {\n  fn default() -> Self {\n    ${name}::${defaultVariant}\n  }\n}`);
     return parts.join("\n");
 }
 function emitUnion(union, program) {
@@ -1046,9 +1066,8 @@ function emitScalar(scalar, program) {
     if (pattern) {
         const rustType = scalarToRust[scalar.name] ?? "String";
         impls.push(`\nimpl TryFrom<String> for ${structName} {\n  type Error = String;\n\n  fn try_from(value: String) -> Result<Self, Self::Error> {\n    let re = regex::Regex::new(r"${pattern}").unwrap();\n    if re.is_match(&value) { Ok(Self(value)) } else { Err(format!("Invalid value: {}", value)) }\n  }\n}`);
-        impls.push(`\nimpl Default for ${structName} {\n  fn default() -> Self {\n    Self(String::new())\n  }\n}`);
         return {
-            typeDef: `#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]\npub struct ${structName}(pub ${rustType});`,
+            typeDef: `#[derive(Debug, Clone, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]\npub struct ${structName}(pub ${rustType});`,
             impls,
         };
     }
@@ -1112,15 +1131,17 @@ export async function $onEmit(context, _options) {
     }
     for (const [enumName, anonEnum] of anonymousEnums) {
         const parts = [];
-        parts.push(`#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]\npub enum ${enumName} {`);
-        for (const literal of anonEnum.variants) {
+        parts.push(`#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]\npub enum ${enumName} {`);
+        for (let i = 0; i < anonEnum.variants.length; i++) {
+            const literal = anonEnum.variants[i];
             const variantName = toRustVariantName(literal.value);
+            if (i === 0) {
+                parts.push(`  #[default]`);
+            }
             parts.push(`  #[serde(rename = "${literal.value}")]`);
             parts.push(`  ${variantName},`);
         }
         parts.push("}");
-        const defaultVariant = toRustVariantName(anonEnum.variants[0]?.value ?? "");
-        parts.push(`\n\nimpl Default for ${enumName} {\n  fn default() -> Self {\n    ${enumName}::${defaultVariant}\n  }\n}`);
         content.push(parts.join("\n"));
         content.push("");
     }
@@ -1145,7 +1166,13 @@ export async function $onEmit(context, _options) {
         content.push("");
     }
     const namespaceGroups = getAllOperations(context.program);
-    const outputContent = "#![allow(unused)]\n\n" + content.join("\n") + "\n";
+    const outputContent = "#![allow(unused)]\n\n" +
+        "use std::str::FromStr;\n" +
+        "use axum::http::StatusCode;\n" +
+        "use axum::response::IntoResponse;\n" +
+        "use axum::Json;\n\n" +
+        content.join("\n") +
+        "\n";
     await emitFile(context.program, {
         path: resolvePath(context.emitterOutputDir, "types.rs"),
         content: outputContent,