Add Azurite TypeSpec emitter prototype

.chronus/changes/azurite-emitter.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azurite-emitter"
+---
+
+Add @azure-tools/typespec-azurite-emitter, a TypeSpec emitter generating Azurite server artifacts (models, route metadata, handler interfaces) from HTTP service definitions.

packages/typespec-azurite-emitter/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

packages/typespec-azurite-emitter/README.md

@@ -0,0 +1,80 @@
+# @azure-tools/typespec-azurite-emitter
+
+Prototype TypeSpec emitter for generating the Queue server artifacts Azurite needs from a
+compiled HTTP service plus an `azurite.tsp` overlay.
+
+The package demonstrates a small but reusable emitter structure:
+
+1. `src/build-model.ts` reads `@typespec/http` operations and TypeSpec models into an
+   emitter-owned server model.
+2. `src/render/` writes three TypeScript files from that model:
+   - `models.ts` — data-model interfaces.
+   - `operations.ts` — request/response types plus route metadata.
+   - `handlers.ts` — handler interface methods with `(params, context)` signatures.
+
+## Usage
+
+```bash
+tsp compile . --emit @azure-tools/typespec-azurite-emitter
+```
+
+or in `tspconfig.yaml`:
+
+```yaml
+emit:
+  - "@azure-tools/typespec-azurite-emitter"
+options:
+  "@azure-tools/typespec-azurite-emitter":
+    outputDir: "." # optional, relative to the emitter output dir
+```
+
+## Azurite overlays
+
+An Azurite-owned overlay can import the shared Storage TypeSpec and apply emulator-specific
+changes without editing the shared source. This package includes `@makeOptional` for required
+properties that the emulator accepts as optional:
+
+```tsp
+import "@azure-tools/typespec-azurite-emitter";
+import "./main.tsp";
+
+using Azurite;
+using Storage.Queues;
+
+@@makeOptional(Storage.Queues.AccessPolicy.start);
+@@makeOptional(Storage.Queues.AccessPolicy.expiry);
+@@makeOptional(Storage.Queues.AccessPolicy.permission);
+```
+
+Core TypeSpec augment decorators can be used for ordinary constraints, for example relaxing the
+Queue visibility-timeout maximum in the overlay:
+
+```tsp
+@@maxValue(Storage.Queues.VisibilityTimeoutParameter.visibilityTimeout, 2147483647);
+```
+
+## Tests
+
+- `test/build-model.test.ts` validates the intermediate model, including operation metadata,
+  referenced models, `Record<T>`, anonymous models, operation-name collisions, and overlay
+  changes.
+- `test/render.test.ts` validates rendering from a hand-built server model.
+- `test/e2e.test.ts` compiles the fixture through the emitter and checks the generated files.
+- `test/azurite-compat.test.ts` checks that generated handler and route-metadata shapes contain
+  what Azurite's Queue runtime needs to wire dispatch and handlers.
+
+Run:
+
+```bash
+pnpm --filter @azure-tools/typespec-azurite-emitter test
+pnpm --filter @azure-tools/typespec-azurite-emitter build
+pnpm --filter @azure-tools/typespec-azurite-emitter lint
+```
+
+## Current scope
+
+This package is intentionally small. It covers the artifact shape and emitter architecture needed
+for a Queue handoff, not a full Storage implementation. The companion Azurite PR validates the
+generated Queue files against Azurite's real runtime. Full XML/model mapper generation, Blob,
+Table/OData, streaming, multipart bodies, versioning, pagination, and richer enum/union rendering
+are future work.

packages/typespec-azurite-emitter/generated-defs/Azurite.ts

@@ -0,0 +1,19 @@
+import type {
+  DecoratorContext,
+  DecoratorValidatorCallbacks,
+  ModelProperty,
+} from "@typespec/compiler";
+
+/**
+ * Marks a model property as optional for Azurite without editing the shared service TypeSpec.
+ *
+ * @param target The model property to make optional.
+ */
+export type MakeOptionalDecorator = (
+  context: DecoratorContext,
+  target: ModelProperty,
+) => DecoratorValidatorCallbacks | void;
+
+export type AzuriteDecorators = {
+  makeOptional: MakeOptionalDecorator;
+};

packages/typespec-azurite-emitter/generated-defs/Azurite.ts-test.ts

@@ -0,0 +1,10 @@
+// An error in the imports would mean that the decorator is not exported or
+// doesn't have the right name.
+
+import { $decorators } from "@azure-tools/typespec-azurite-emitter";
+import type { AzuriteDecorators } from "./Azurite.js";
+
+/**
+ * An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ...
+ */
+const _decs: AzuriteDecorators = $decorators["Azurite"];

packages/typespec-azurite-emitter/lib/decorators.tsp

@@ -0,0 +1,12 @@
+import "../dist/src/index.js";
+
+using Reflection;
+
+namespace Azurite;
+
+/**
+ * Marks a model property as optional for Azurite without editing the shared service TypeSpec.
+ *
+ * @param target The model property to make optional.
+ */
+extern dec makeOptional(target: ModelProperty);

packages/typespec-azurite-emitter/lib/main.tsp

@@ -0,0 +1 @@
+import "./decorators.tsp";

packages/typespec-azurite-emitter/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@azure-tools/typespec-azurite-emitter",
+  "version": "0.1.0",
+  "description": "TypeSpec emitter generating Azurite server artifacts (models, route metadata, handler interfaces).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Microsoft Corporation",
+  "keywords": [
+    "typespec",
+    "emitter",
+    "azurite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Azure/typespec-azure.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Azure/typespec-azure/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "tspMain": "lib/main.tsp",
+  "files": [
+    "lib/**",
+    "dist/**",
+    "!dist/test/**"
+  ],
+  "exports": {
+    ".": {
+      "typespec": "./lib/main.tsp",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "pnpm gen-extern-signature && tsc -p tsconfig.build.json",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rimraf ./dist ./temp",
+    "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
+    "lint": "oxlint . --deny-warnings",
+    "lint:fix": "oxlint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest -w",
+    "test:ui": "vitest --ui",
+    "test:ci": "vitest run --coverage  --reporter=junit --reporter=default"
+  },
+  "peerDependencies": {
+    "@azure-tools/typespec-client-generator-core": "workspace:^",
+    "@typespec/compiler": "workspace:^",
+    "@typespec/http": "workspace:^"
+  },
+  "devDependencies": {
+    "@azure-tools/typespec-client-generator-core": "workspace:^",
+    "@types/node": "catalog:",
+    "@typespec/compiler": "workspace:^",
+    "@typespec/http": "workspace:^",
+    "@typespec/tspd": "workspace:^",
+    "@vitest/coverage-v8": "catalog:",
+    "@vitest/ui": "catalog:",
+    "rimraf": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}