typespec-rust-emitter 0.1.0

package/dist/test/hello.test.js

@@ -0,0 +1,140 @@
+import { strictEqual } from "node:assert";
+import { describe, it } from "node:test";
+import { emit } from "./test-host.js";
+describe("Rust emitter", () => {
+    it("emits basic model", async () => {
+        const results = await emit(`
+      model User {
+        name: string;
+        age: int32;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("pub struct User"), true);
+        strictEqual(output.includes("pub name: String,"), true);
+        strictEqual(output.includes("pub age: i32,"), true);
+    });
+    it("emits optional properties", async () => {
+        const results = await emit(`
+      model Person {
+        firstName: string;
+        middleName?: string;
+        lastName: string;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes('#[serde(rename = "firstName")]'), true);
+        strictEqual(output.includes("pub first_name: String,"), true);
+        strictEqual(output.includes('#[serde(rename = "middleName")]'), true);
+        strictEqual(output.includes("pub middle_name: Option<String>,"), true);
+        strictEqual(output.includes("#[serde(skip_serializing_if"), true);
+        strictEqual(output.includes('#[serde(rename = "lastName")]'), true);
+        strictEqual(output.includes("pub last_name: String,"), true);
+    });
+    it("emits string enum", async () => {
+        const results = await emit(`
+      enum Status {
+        active,
+        inactive,
+        pending,
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("pub enum Status"), true);
+        strictEqual(output.includes('#[serde(rename = "active")]'), true);
+        strictEqual(output.includes("Active,"), true);
+        strictEqual(output.includes("Inactive,"), true);
+        strictEqual(output.includes("Pending,"), true);
+    });
+    it("emits integer enum", async () => {
+        const results = await emit(`
+      enum Priority {
+        low: 1,
+        medium: 2,
+        high: 3,
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("pub enum Priority"), true);
+        strictEqual(output.includes("Low = 1,"), true);
+        strictEqual(output.includes("Medium = 2,"), true);
+        strictEqual(output.includes("High = 3,"), true);
+    });
+    it("emits nested models", async () => {
+        const results = await emit(`
+      model Address {
+        street: string;
+        city: string;
+      }
+      
+      model User {
+        name: string;
+        address: Address;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("pub struct Address"), true);
+        strictEqual(output.includes("pub struct User"), true);
+        strictEqual(output.includes("pub address: Address,"), true);
+    });
+    it("includes serde derive macros", async () => {
+        const results = await emit(`
+      model Test {
+        value: string;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]"), true);
+    });
+    it("emits arrays as Vec", async () => {
+        const results = await emit(`
+      model Test {
+        items: string[];
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("pub items: Vec<String>,"), true);
+    });
+    it("emits maps as HashMap", async () => {
+        const results = await emit(`
+      model Test {
+        metadata: Record<string>;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("std::collections::HashMap<String, String>"), true);
+    });
+    it("emits nullable types as Option", async () => {
+        const results = await emit(`
+      model Test {
+        deletedAt: string | null;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes('#[serde(rename = "deletedAt")]'), true);
+        strictEqual(output.includes("pub deleted_at: Option<String>,"), true);
+    });
+    it("emits custom rustDerive macros", async () => {
+        const results = await emit(`
+      import "typespec-rust-emitter";
+      
+      @rustDerive("sqlx::FromRow")
+      model User {
+        name: string;
+        age: int32;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]"), true);
+    });
+    it("emits multiple rustDerive macros via $rustDerives", async () => {
+        const results = await emit(`
+      model Statistics {
+        count: int32;
+      }
+    `);
+        const output = results["types.rs"];
+        strictEqual(output.includes("#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]"), true);
+    });
+});
+//# sourceMappingURL=hello.test.js.map

package/dist/test/hello.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hello.test.js","sourceRoot":"","sources":["../../test/hello.test.ts"],"names":[],"mappings":"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"}

package/dist/test/test-host.d.ts

@@ -0,0 +1,4 @@
+import { Diagnostic } from "@typespec/compiler";
+export declare const Tester: import("@typespec/compiler/testing").EmitterTester<import("@typespec/compiler/testing").TestEmitterCompileResult>;
+export declare function emitWithDiagnostics(code: string): Promise<[Record<string, string>, readonly Diagnostic[]]>;
+export declare function emit(code: string): Promise<Record<string, string>>;

package/dist/test/test-host.js

@@ -0,0 +1,16 @@
+import { resolvePath } from "@typespec/compiler";
+import { expectDiagnosticEmpty } from "@typespec/compiler/testing";
+import { createTester } from "@typespec/compiler/testing";
+export const Tester = createTester(resolvePath(import.meta.dirname, "../.."), {
+    libraries: ["typespec-rust-emitter"],
+}).emit("typespec-rust-emitter");
+export async function emitWithDiagnostics(code) {
+    const [{ outputs }, diagnostics] = await Tester.compileAndDiagnose(code);
+    return [outputs, diagnostics];
+}
+export async function emit(code) {
+    const [result, diagnostics] = await emitWithDiagnostics(code);
+    expectDiagnosticEmpty(diagnostics);
+    return result;
+}
+//# sourceMappingURL=test-host.js.map

package/dist/test/test-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-host.js","sourceRoot":"","sources":["../../test/test-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE;IAC5E,SAAS,EAAE,CAAC,uBAAuB,CAAC;CACrC,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;AAEjC,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAY;IAEZ,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,WAAW,CAAC,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACzE,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAY;IACrC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC9D,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/eslint.config.js

@@ -0,0 +1,20 @@
+// @ts-check
+import eslint from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import tsEslint from "typescript-eslint";
+
+export default defineConfig(
+  {
+    ignores: ["**/dist/**/*", "**/.temp/**/*"],
+  },
+  eslint.configs.recommended,
+  ...tsEslint.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { varsIgnorePattern: "^_", argsIgnorePattern: "^_" },
+      ],
+    },
+  },
+);

package/example/lib/learning/models.tsp

@@ -0,0 +1,189 @@
+import "typespec-rust-emitter";
+
+namespace Mtlkms.Learning.Models {
+  // ── COMMON ─────────────────────────────────────────────────────────────────
+
+  @error
+  model ApiError {
+    @doc("Machine-readable error code.")
+    code: string;
+
+    @doc("Human-readable message.")
+    message: string;
+  }
+
+  model NotFoundError extends ApiError {
+    code: "NOT_FOUND";
+  }
+  model ValidationError extends ApiError {
+    code: "VALIDATION_ERROR";
+  }
+  model ConflictError extends ApiError {
+    code: "CONFLICT";
+  }
+
+  // ── SCALARS & ENUMS ───────────────────────────────────────────────────────
+
+  @format("uuid")
+  scalar Uuid extends string;
+
+  @pattern("^#[0-9A-Fa-f]{6}$")
+  scalar HexColor extends string;
+
+  enum StudyStatus {
+    Starting: "Starting",
+    Paused: "Paused",
+    Stopped: "Stopped",
+  }
+
+  enum ChartGranularity {
+    Day: "day",
+    Week: "week",
+    Month: "month",
+    Year: "year",
+  }
+
+  // ── AGGREGATION MIXIN ──────────────────────────────────────────────────────
+
+  @doc("Duration statistics calculated in real-time from timelogs. Unit: seconds.")
+  model DurationStats {
+    durationTotal: int64;
+    durationDay: int64;
+    durationWeek: int64;
+    durationMonth: int64;
+  }
+
+  // ── MODELS: GROUP ─────────────────────────────────────────────────────────
+
+  model Group {
+    id: int64;
+    accountId: Uuid;
+    createdAt: utcDateTime;
+    deletedAt: utcDateTime | null;
+
+    @maxLength(255)
+    name: string;
+
+    @maxLength(44)
+    icon: string;
+
+    colorText: HexColor;
+    colorBg: HexColor;
+  }
+
+  @rustDerive("sqlx::FromRow")
+  model GroupStatistics {
+    ...Group;
+    subjectCount: int64;
+    status: StudyStatus;
+    ...DurationStats;
+  }
+
+  model CreateGroupBody {
+    @maxLength(255)
+    name: string;
+
+    @maxLength(44)
+    icon: string;
+
+    colorText: HexColor;
+    colorBg: HexColor;
+  }
+
+  model UpdateGroupBody {
+    @maxLength(255)
+    name?: string;
+
+    @maxLength(44)
+    icon?: string;
+
+    colorText?: HexColor;
+    colorBg?: HexColor;
+  }
+
+  // ── MODELS: SUBJECT ───────────────────────────────────────────────────────
+
+  model Subject {
+    id: int64;
+    accountId: Uuid;
+    groupId: int64;
+    createdAt: utcDateTime;
+    deletedAt: utcDateTime | null;
+
+    @maxLength(255)
+    name: string;
+
+    @maxLength(44)
+    icon: string;
+
+    colorText: HexColor;
+    colorBg: HexColor;
+  }
+
+  model SubjectStatistics {
+    ...Subject;
+    status: StudyStatus;
+    ...DurationStats;
+  }
+
+  model CreateSubjectBody {
+    @maxLength(255)
+    name: string;
+
+    @maxLength(44)
+    icon: string;
+
+    colorText: HexColor;
+    colorBg: HexColor;
+  }
+
+  model UpdateSubjectBody {
+    @maxLength(255)
+    name?: string;
+
+    @maxLength(44)
+    icon?: string;
+
+    colorText?: HexColor;
+    colorBg?: HexColor;
+  }
+
+  // ── MODELS: SESSION ───────────────────────────────────────────────────────
+
+  model Log {
+    id: int64;
+    accountId: Uuid;
+    subjectId: int64;
+    startedAt: utcDateTime;
+    stoppedAt: utcDateTime | null;
+    logContent: string | null;
+    status: StudyStatus;
+  }
+
+  model Timelog {
+    id: int64;
+    accountId: Uuid;
+    logId: int64;
+    subjectId: int64;
+    startedAt: utcDateTime;
+    stoppedAt: utcDateTime | null;
+    durationInSeconds: int64;
+  }
+
+  @doc("Response after start/resume — returns the log and the newly opened timelog segment.")
+  model SessionOpenedResponse {
+    log: Log;
+    timelog: Timelog;
+  }
+
+  @doc("Response after pause/stop — returns the log and the newly closed timelog segment.")
+  model SessionClosedResponse {
+    log: Log;
+    timelog: Timelog;
+  }
+
+  @doc("Optional payload for start or stop operations — contains a note for the session.")
+  model SessionNoteBody {
+    logContent?: string;
+  }
+}

package/example/lib/learning/operations.tsp

@@ -0,0 +1,319 @@
+import "@typespec/http";
+import "./models.tsp";
+
+using TypeSpec.Http;
+using Mtlkms.Learning.Models;
+
+@route("/learning")
+namespace Mtlkms.Learning;
+
+@route("/groups")
+@tag("Groups")
+namespace Groups {
+  @get
+  @doc("Retrieve a list of all groups for the current account (from view_learning_group).")
+  op list(): {
+    @statusCode statusCode: 200;
+    @body body: GroupStatistics[];
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  };
+
+  @post
+  @useAuth(BearerAuth)
+  @doc("Create a new group.")
+  op create(@body body: CreateGroupBody): {
+    @statusCode statusCode: 201;
+    @body body: Group;
+  } | {
+    @statusCode statusCode: 400;
+    @body error: ValidationError;
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  };
+
+  @get
+  @route("/{id}")
+  @doc("Get the details of a group by its ID.")
+  op getById(@path id: int64): {
+    @statusCode statusCode: 200;
+    @body body: GroupStatistics;
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  } | {
+    @statusCode statusCode: 404;
+    @body error: NotFoundError;
+  };
+
+  @patch
+  @route("/{id}")
+  @useAuth(BearerAuth)
+  @doc("Update a group. Only provide the fields that need to be changed.")
+  op update(@path id: int64, @body body: UpdateGroupBody):
+    | {
+        @statusCode statusCode: 200;
+        @body body: Group;
+      }
+    | {
+        @statusCode statusCode: 400;
+        @body error: ValidationError;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      };
+
+  @delete
+  @route("/{id}")
+  @useAuth(BearerAuth)
+  @doc("Soft delete a group. All subjects within the group will also be soft deleted.")
+  op delete(@path id: int64): {
+    @statusCode statusCode: 204;
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  } | {
+    @statusCode statusCode: 404;
+    @body error: NotFoundError;
+  };
+}
+
+@route("/groups/{groupId}/subjects")
+@tag("Subjects")
+namespace Subjects {
+  @get
+  @doc("Retrieve a list of subjects for a group (from view_subject_statistics).")
+  op list(@path groupId: int64): {
+    @statusCode statusCode: 200;
+    @body body: SubjectStatistics[];
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  } | {
+    @statusCode statusCode: 404;
+
+    @doc("The group does not exist.")
+    @body
+    error: NotFoundError;
+  };
+
+  @post
+  @useAuth(BearerAuth)
+  @doc("Create a new subject within the specified group.")
+  op create(@path groupId: int64, @body body: CreateSubjectBody):
+    | {
+        @statusCode statusCode: 201;
+        @body body: Subject;
+      }
+    | {
+        @statusCode statusCode: 400;
+        @body error: ValidationError;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      };
+
+  @get
+  @route("/{id}")
+  @doc("Get the details of a subject by its ID.")
+  op getById(@path groupId: int64, @path id: int64): {
+    @statusCode statusCode: 200;
+    @body body: SubjectStatistics;
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  } | {
+    @statusCode statusCode: 404;
+    @body error: NotFoundError;
+  };
+
+  @patch
+  @route("/{id}")
+  @useAuth(BearerAuth)
+  @doc("Update a subject. Only provide the fields that need to be changed.")
+  op update(
+    @path groupId: int64,
+    @path id: int64,
+    @body body: UpdateSubjectBody,
+  ):
+    | {
+        @statusCode statusCode: 200;
+        @body body: Subject;
+      }
+    | {
+        @statusCode statusCode: 400;
+        @body error: ValidationError;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      };
+
+  @delete
+  @route("/{id}")
+  @useAuth(BearerAuth)
+  @doc("Soft delete a subject.")
+  op delete(@path groupId: int64, @path id: int64): {
+    @statusCode statusCode: 204;
+  } | {
+    @statusCode statusCode: 401;
+    @body error: ApiError;
+  } | {
+    @statusCode statusCode: 404;
+    @body error: NotFoundError;
+  };
+}
+
+// ── NAMESPACE: SESSIONS ───────────────────────────────────────────────────
+// State machine:
+//
+//   (none) ──start──► Starting ──pause──► Paused
+//                        ▲                  │
+//                        └────resume─────────┘
+//                        │
+//                      stop
+//                        │
+//                        ▼
+//                     Stopped
+//
+// Each start/resume operation opens a new Timelog.
+// Each pause/stop operation closes the current Timelog (sets stoppedAt and calculates durationInSeconds).
+
+@route("/subjects/{subjectId}/sessions")
+@tag("Sessions")
+namespace Sessions {
+  @post
+  @useAuth(BearerAuth)
+  @doc("""
+      Start a new study session for the subject.
+      The server creates a Log (status=Starting) and the first Timelog.
+      Returns 409 if the subject already has a session in Starting or Paused status.
+    """)
+  op start(@path subjectId: int64, @body body: SessionNoteBody):
+    | {
+        @statusCode statusCode: 201;
+        @body body: SessionOpenedResponse;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      }
+    | {
+        @statusCode statusCode: 409;
+
+        @doc("The subject already has an active session (status is Starting or Paused).")
+        @body
+        error: ConflictError;
+      };
+
+  @post
+  @route("/{logId}/pause")
+  @useAuth(BearerAuth)
+  @doc("""
+      Pause the currently running session (transition from Starting to Paused).
+      The server closes the current Timelog (sets stoppedAt and calculates durationInSeconds).
+      Returns 409 if the session is not in the Starting state.
+    """)
+  op pause(@path subjectId: int64, @path logId: int64):
+    | {
+        @statusCode statusCode: 200;
+        @body body: SessionClosedResponse;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      }
+    | {
+        @statusCode statusCode: 409;
+
+        @doc("The session is not in the Starting state.")
+        @body
+        error: ConflictError;
+      };
+
+  @post
+  @route("/{logId}/resume")
+  @useAuth(BearerAuth)
+  @doc("""
+      Resume a paused session (transition from Paused to Starting).
+      The server creates a new Timelog.
+      Returns 409 if the session is not in the Paused state.
+    """)
+  op resume(@path subjectId: int64, @path logId: int64):
+    | {
+        @statusCode statusCode: 200;
+        @body body: SessionOpenedResponse;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      }
+    | {
+        @statusCode statusCode: 409;
+
+        @doc("The session is not in the Paused state.")
+        @body
+        error: ConflictError;
+      };
+
+  @post
+  @route("/{logId}/stop")
+  @useAuth(BearerAuth)
+  @doc("""
+      End the session (transition from Starting or Paused to Stopped).
+      The server closes the current Timelog if it is running, and updates Log.stoppedAt.
+      Returns 409 if the session is already Stopped.
+    """)
+  op stop(
+    @path subjectId: int64,
+    @path logId: int64,
+    @body body: SessionNoteBody,
+  ):
+    | {
+        @statusCode statusCode: 200;
+        @body body: SessionClosedResponse;
+      }
+    | {
+        @statusCode statusCode: 401;
+        @body error: ApiError;
+      }
+    | {
+        @statusCode statusCode: 404;
+        @body error: NotFoundError;
+      }
+    | {
+        @statusCode statusCode: 409;
+
+        @doc("The session is already in the Stopped state.")
+        @body
+        error: ConflictError;
+      };
+}