@tertiumorganum/typespec-amqp-ws 0.0.2 → 0.0.3

package/README.md

@@ -282,10 +282,6 @@ model M { payload: MPayload; }
 - `ws-discriminator.tsp` — WebSocket с literal-дискриминатором.
 - `ws-reply.tsp` — WebSocket с request/reply.
 
-## Контрибьюции
-
-Pull-requests и issues приветствуются. Это утилита под конкретный воркфлоу; решения по новым фичам принимаются исходя из того, насколько они вписываются в принцип "узкий набор фич для типичных кейсов".
-
 ## Лицензия
 
 [MIT](LICENSE).

package/docs/README.md

@@ -0,0 +1,48 @@
+# Документация `typespec-amqp-ws`
+
+Эмиттер TypeSpec для генерации AsyncAPI 3.0 спецификаций.
+
+## Содержание
+
+- [usage.md](usage.md) — Установка, конфигурация, синтаксис, поддерживаемые типы, типичные сценарии использования.
+- [architecture.md](architecture.md) — Внутреннее устройство эмиттера: модули, поток данных, принципы преобразования TypeSpec в JSON Schema, особенности реализации.
+
+## TL;DR
+
+`typespec-amqp-ws` — это TypeSpec-эмиттер, который превращает декларативное описание сервиса на TypeSpec в YAML-файл AsyncAPI 3.0. Поддерживает два транспорта:
+
+- **AMQP (RabbitMQ)** — publish в exchange, consume из очереди, exchange-типы `direct` и `fanout`.
+- **WebSocket** — единый канал `/`, дискриминатор сообщений через literal-типы, request/reply, бинарные сообщения через `contentType: application/octet-stream`.
+
+Эмиттер задуман с осознанным **ограниченным** объёмом фич: только то, что реально нужно для микросервисов команды. Не Kafka, не MQTT, не security schemes, не topic-exchanges, не numeric enums. Из-за этого его реализация и API проще, чем у универсальных AsyncAPI-эмиттеров.
+
+## Минимальный пример
+
+```typespec
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "My Service" })
+@info(#{ version: "1.0.0" })
+@server("rabbit", #{ host: "localhost:5672", protocol: "amqp" })
+namespace MyService;
+
+model Event {
+  id: string;
+  payload: string;
+}
+
+@publish(#{
+  routingKey: "events.created",
+  exchange: #{ name: "events", type: "direct", durable: true },
+})
+op sendEvent(): Event;
+```
+
+После `tsp compile .` получите валидный `asyncapi.yaml`, который скармливается стандартным инструментам — `modelina` для генерации Go/TS-моделей, `redocly` для HTML-документации.
+
+## Лицензия
+
+[MIT](../LICENSE).

package/docs/architecture.md

@@ -0,0 +1,319 @@
+# Архитектура `typespec-amqp-ws`
+
+Этот документ — для тех, кто разрабатывает или модифицирует эмиттер. Описывает внутреннее устройство, ключевые архитектурные решения и точки расширения.
+
+## Общая картина
+
+```
+TypeSpec sources (.tsp)
+        │
+        ▼ tsp compile
+TypeSpec compiler AST + decorator state map
+        │
+        ▼ $onEmit($context)
+┌────────────────────────────────────────────────┐
+│  emitAsyncApi(context, target)                 │
+│  ├─ buildServiceInfo  (info + servers)         │
+│  ├─ SchemaBuilder     (модели/enum/scalars)    │
+│  ├─ buildAmqp  либо  buildWs                   │
+│  │   (channels + operations + messages)        │
+│  └─ serialize → YAML/JSON                      │
+└────────────────────────────────────────────────┘
+        │
+        ▼ writeFile
+asyncapi.yaml (или .json)
+```
+
+Эмиттер построен на **`@typespec/asset-emitter`** — тот же фреймворк, на котором работают официальные `@typespec/openapi3` и `@typespec/json-schema`. Это даёт нам стандартные механизмы для разрешения `$ref`-ссылок, именования схем, обхода типов компилятора.
+
+## Структура пакета
+
+```
+asyncapi/
+├── package.json                   # exports: ".", "./amqp", "./ws", "./testing"
+├── lib/
+│   ├── main.tsp                   # точка входа (импортируется при `import "typespec-amqp-ws"`)
+│   ├── amqp.tsp                   # объявления декораторов TspAsyncApi.Amqp
+│   └── ws.tsp                     # объявления декораторов TspAsyncApi.WebSocket
+├── src/
+│   ├── index.ts                   # корневой entry: экспортирует $lib
+│   ├── shared/
+│   │   ├── lib.ts                 # createTypeSpecLibrary, диагностики, опции
+│   │   ├── options.ts             # JSON Schema опций эмиттера
+│   │   ├── state.ts               # Symbol-ключи для program.stateMap
+│   │   ├── document.ts            # типы AsyncApiDoc, AsyncApiOperation и т.п.
+│   │   ├── schema-emitter.ts      # SchemaBuilder: TypeSpec → JSON Schema
+│   │   ├── decorators-service.ts  # @info, @server (namespace = "TspAsyncApi")
+│   │   ├── asyncapi-emitter.ts    # оркестратор emitAsyncApi()
+│   │   └── yaml-writer.ts         # сериализация YAML/JSON
+│   ├── amqp/
+│   │   ├── index.ts               # $onEmit для AMQP-таргета
+│   │   ├── decorators.ts          # @publish, @consume, @message (namespace = "TspAsyncApi.Amqp")
+│   │   └── builder.ts             # buildAmqp(program, doc)
+│   └── ws/
+│       ├── index.ts               # $onEmit для WS-таргета
+│       ├── decorators.ts          # @publish, @consume, @reply, @binary, @message (namespace = "TspAsyncApi.WebSocket")
+│       └── builder.ts             # buildWs(program, doc)
+└── test/                          # vitest-тесты
+```
+
+## Ключевые решения
+
+### Один пакет — два emit-таргета
+
+`typespec-amqp-ws` экспортирует два независимых эмиттера через **sub-path exports** в `package.json`:
+
+```json
+"exports": {
+  ".": { ... },           // корневые декораторы (@info, @server)
+  "./amqp": { ... },      // $onEmit для AMQP
+  "./ws": { ... }         // $onEmit для WebSocket
+}
+```
+
+Пользователь подключает один из них в `tspconfig.yaml`:
+
+```yaml
+emit:
+  - "typespec-amqp-ws/amqp"   # или "/ws"
+```
+
+**Почему так**: каждый сервис должен иметь либо AMQP, либо WebSocket API. Смешивать их в одном `asyncapi.yaml` — концептуально неправильно (разные транспорты, разные паттерны). Два emit-таргета обеспечивают чёткое разделение, при этом весь общий код (схемы, info, servers) живёт в `src/shared/`.
+
+Эта возможность (`exports` с sub-paths в TypeSpec-пакете) появилась в TypeSpec 1.0+. До 1.0 пришлось бы делать два отдельных npm-пакета.
+
+### Декораторы — три namespace, три JS-модуля
+
+| TypeSpec namespace | JS-модуль (с `export const namespace`) |
+|---|---|
+| `TspAsyncApi` | `src/shared/decorators-service.ts` |
+| `TspAsyncApi.Amqp` | `src/amqp/decorators.ts` |
+| `TspAsyncApi.WebSocket` | `src/ws/decorators.ts` |
+
+Каждый JS-модуль с декораторами объявляет `export const namespace = "..."`. Это **обязательное соглашение** TypeSpec — компилятор по этому экспорту узнаёт, к какому namespace относятся `$decoratorName`-функции из этого файла.
+
+Все три файла импортируются в `lib/main.tsp` через `import "../dist/src/.../decorators.js"`. Когда пользователь пишет `import "typespec-amqp-ws"`, эта цепочка подгружает декораторы.
+
+### Декораторы только пишут в state, эмиттер только читает
+
+Все декораторы устроены одинаково:
+
+```typescript
+export function $publish(context: DecoratorContext, target: Operation, config: PublishConfig): void {
+  // (опциональная валидация config)
+  context.program.stateMap(AmqpPublishKey).set(target, config);
+}
+```
+
+Они **не** делают эмит, не модифицируют типы, не обращаются к другим декораторам. Это правило TypeSpec — порядок выполнения декораторов относительно других файлов не гарантирован, поэтому декоратор должен только сохранять данные.
+
+Эмиттер `$onEmit` затем обходит программу через `navigateProgram` и читает state.
+
+### State-keys через Symbol.for()
+
+```typescript
+// src/shared/state.ts
+export const AmqpPublishKey = Symbol.for("typespec-amqp-ws.amqp.publish");
+export const AmqpConsumeKey = Symbol.for("typespec-amqp-ws.amqp.consume");
+// ...
+```
+
+`Symbol.for(...)` создаёт глобальный symbol — два разных JS-модуля, получающие symbol с одной строкой, получат **тот же** symbol. Это важно, потому что декораторы и эмиттер живут в разных файлах, но обращаются к одному state.
+
+### `@typespec/asset-emitter` vs самописный обход
+
+Для большинства схемных типов мы используем **самописный обход** через `navigateProgram`. `@typespec/asset-emitter` (TypeEmitter) обеспечивает только общую инфраструктуру — `$ref` resolution мы делаем вручную через имена.
+
+**Почему так**: наш набор типов узкий (запрещены циклические зависимости через `Union`, нет `oneOf`/`anyOf`), и простой `navigateProgram + map имён в namedSchemas` справляется. TypeEmitter добавил бы сложности (lifecycle методы, кэширование), которая для нашего объёма не окупается.
+
+### Запрет анонимных моделей в полях
+
+Принципиальное решение: анонимные `{...}`-объекты в полях запрещены. Только именованные `model X`.
+
+```typespec
+// ❌ ошибка эмиттера
+model M {
+  payload: { foo: string };
+}
+```
+
+**Почему**: `modelina` (генератор Go/TS моделей) требует осмысленных имён для типов. Авто-генерация имён (`AnonymousSchema1`, и т.п.) ненадёжна и непредсказуема. Запрет на старте проще, чем чинить потом.
+
+### `additionalProperties: false` по умолчанию
+
+В отличие от `@typespec/openapi3` (где `additionalProperties` по умолчанию не указан, что эквивалентно "разрешены"), у нас на **каждой** модели объекта по умолчанию `additionalProperties: false`.
+
+**Почему**: это соответствует руко­писной AsyncAPI-конвенции команды. "Зачем мне в структуры произвольно добавлять всякую фигню" (с) — лучше быть строгим по умолчанию.
+
+### Узкий белый список типов с диагностиками
+
+В `SchemaBuilder.scalarSchema` и связанной логике мы **явно отбрасываем**:
+- Размер-специфичные int (int8/16/32, uint8/16/32) → ошибка `unsupported-sized-int`
+- 64-битные числа → ошибка `unsupported-int64`
+- Float / decimal → ошибка `unsupported-float`
+- Date / time типы → ошибка `unsupported-temporal`
+- URL → ошибка `unsupported-url`
+- `safeint`/`numeric` → ошибка `unsupported-fuzzy-numeric`
+
+**Почему**: эмпирически проверено, что modelina и openapi-generator-cli **игнорируют** `format` подсказки и генерируют `int32`/`number`/`string` независимо. Размер-специфичные типы создают ложное ожидание. На границе между языками (C++, Go, TypeScript) переносимо работают только `string`, `boolean`, `integer`, `bytes`. Любой другой числовой тип — мина под кодгеном.
+
+### `allOf`-обёртка для $ref с description
+
+Если у поля модели есть `@doc`, а тип — именованный (scalar или другая model), то генерируется:
+
+```yaml
+field:
+  allOf:
+    - $ref: '#/components/schemas/SomeType'
+  description: "пояснение"
+```
+
+**Почему**: JSON Schema запрещает рядом с `$ref` иметь другие keywords. `allOf` — стандартный обход этого ограничения. Это копия поведения `@typespec/openapi3` — гарантирует совместимость с тем же `modelina`.
+
+### Namespace-префикс через `.`
+
+```typespec
+namespace MyService;
+namespace business_event {
+  model TokenIssued { ... }
+}
+```
+
+→
+```yaml
+components.schemas:
+  business_event.TokenIssued: ...
+```
+
+Корневой service-namespace (`MyService`) **не входит** в префикс — он считается "scope" сервиса. Вложенные namespace — входят через `.`.
+
+Это копия поведения `@typespec/openapi3` для имён схем (для operationId openapi3 использует `_`, но у AsyncAPI нет operationId как такового — все ключи в `operations:` объекте).
+
+## Поток обработки
+
+### 1. Декораторы пишут state
+
+При обходе `.tsp`-файлов компилятор вызывает декораторы. Они записывают конфиги в `program.stateMap(<Key>)`:
+
+```
+@publish(#{...})  →  AmqpPublishKey.set(operation, config)
+@consume(#{...})  →  AmqpConsumeKey.set(operation, config)
+@reply(M)         →  WsReplyKey.set(operation, M)
+@binary           →  WsBinaryKey.set(operation, true)
+@info(#{...})     →  InfoKey.set(namespace, config)
+@server(name, ...) →  ServerKey.set(namespace, Map<string, ServerConfig>)
+```
+
+### 2. `$onEmit(context)` запускается компилятором после AST-парсинга
+
+`src/amqp/index.ts` (или `src/ws/index.ts`) экспортирует `$onEmit`, который делегирует в `emitAsyncApi(context, "amqp"|"ws")`.
+
+### 3. `emitAsyncApi` собирает документ
+
+```typescript
+const doc: AsyncApiDoc = emptyDoc();         // { asyncapi: "3.0.0", info: ... }
+buildServiceInfo(context, doc);              // info + servers
+new SchemaBuilder(program).collect();        // обход моделей/enums/scalars
+                                             // → components.schemas
+buildAmqp(program, doc);  // или buildWs     // channels + operations + messages
+serialize(doc, opts);                        // → YAML или JSON
+host.writeFile(path, text);                  // mkdirp + write
+```
+
+### 4. SchemaBuilder обход
+
+```typescript
+navigateProgram(program, {
+  model: m => this.addModel(m),
+  enum: e => this.addEnum(e),
+  scalar: s => this.addScalar(s),
+});
+```
+
+Для каждого типа `addX` фильтрует stdlib (`isInLibraryNs`), конструирует JSON Schema-фрагмент, кладёт в `namedSchemas`. Поля модели рекурсивно обрабатываются через `schemaFor(prop.type)`.
+
+### 5. buildAmqp / buildWs
+
+```typescript
+navigateProgram(program, {
+  operation(op) {
+    const pub = program.stateMap(AmqpPublishKey).get(op);
+    const con = program.stateMap(AmqpConsumeKey).get(op);
+    if (pub) attachPublish(...);
+    else if (con) attachConsume(...);
+  },
+});
+```
+
+`attachPublish` собирает channel + operation + message:
+
+```typescript
+doc.channels[channelKey] = {
+  address: config.routingKey,
+  bindings: { amqp: { is: "routingKey", exchange: cleanExchange(config.exchange) } },
+  messages: { [messageKey]: { $ref: ... } },
+};
+doc.operations[op.name] = {
+  action: "send",
+  channel: { $ref: ... },
+  messages: [{ $ref: ... }],
+  summary, description,
+};
+doc.components.messages[messageKey] = {
+  payload: { $ref: `#/components/schemas/${returnTypeName}` },
+};
+```
+
+`buildWs` устроен похоже, но все операции сворачивает на единый канал `/`, плюс обрабатывает `@reply` и `@binary`.
+
+### 6. Сериализация
+
+`yaml.dump(doc, { lineWidth: 120, noRefs: true, sortKeys: false })`. `sortKeys: false` сохраняет порядок вставки полей в JS-объекте — поэтому документ читается в логическом порядке (asyncapi → info → servers → channels → operations → components).
+
+## Тестирование
+
+Тесты на `vitest`. Главный харнесс — `test/utils/test-host.ts`:
+
+```typescript
+const result = await emit(`...TypeSpec код...`, "amqp" | "ws");
+expectNoErrors(result);
+expect(result.doc.components.schemas.X).toEqual({...});
+```
+
+Под капотом `emit()` использует `createTestHost` + `createTestWrapper` из `@typespec/compiler/testing`. Все имеющиеся `tsp`-фикстуры компилируются в виртуальной FS, эмиттер пишет туда `asyncapi.yaml`, мы его парсим и инспектим.
+
+Snapshot-тесты на нескольких end-to-end фикстурах в `test/fixtures/` (по одному файлу на типичный сценарий: AMQP send+receive, AMQP fanout, WebSocket с дискриминатором, WebSocket с reply и binary) лежат в `test/__snapshots__/fixtures.test.ts.snap` — это контракт регрессии.
+
+## Точки расширения
+
+### Добавить новый AsyncAPI binding (например, Kafka)
+
+1. Создать `src/kafka/` с `decorators.ts` (namespace = "TspAsyncApi.Kafka") и `builder.ts`
+2. Добавить `lib/kafka.tsp` с extern dec'ами
+3. Импортировать `lib/kafka.tsp` в `lib/main.tsp`
+4. Добавить новый emit-таргет: `"./kafka"` в `package.json` exports, `src/kafka/index.ts` с `$onEmit`
+5. В `emitAsyncApi` (или общем switch) добавить ветку `if (target === "kafka") buildKafka(...)`
+6. Добавить тесты
+
+### Поддержать новый TypeSpec-тип в схемах
+
+В `src/shared/schema-emitter.ts` метод `schemaFor(type)` — это switch по `type.kind`. Добавить ветку и при необходимости — отдельный `addX(...)` для именованных типов.
+
+### Новая диагностика
+
+В `src/shared/lib.ts` секция `diagnostics:` — добавить новый код с `severity`, `messages.default` (с `paramMessage` для интерполяции). Использовать в коде через `reportDiagnostic(program, { code, target, format })`.
+
+## Совместимость
+
+- `@typespec/compiler` ^1.12.0 — API стабилен (1.0+).
+- `@typespec/asset-emitter` ^0.79.0 — пока pre-1.0, может ломаться в будущем.
+- Тестируется на Node.js 22+ и 24+.
+
+Запас совместимости с TypeSpec API минимальный — мы используем `@typespec/compiler` напрямую (типы `Type`, `Model`, `Enum`, `Scalar`, `Operation`, `Namespace`, `Union`). Если они мигрируют — придётся обновлять. Сейчас в 1.x намерение Microsoft — держать API стабильным.
+
+## Известные ограничения
+
+- **Циклические зависимости в Union** не поддерживаются (валится в `unionSchema`). На практике для наших сервисов не используются.
+- **Только `T | null` форма Union**. Прочие union'ы — диагностика `unsupported-union`. Если нужны поли­морфные сообщения в будущем — потребуется реализация `oneOf`/`discriminator`.
+- **Реальная FS** — `writeFile` требует чтобы родительская директория существовала (для test-FS она auto-create). Мы делаем `host.mkdirp` перед записью.
+- **Версия AsyncAPI** хардкоднута на `3.0.0`. Для 3.1 нужно поменять одну константу в `document.ts` и проверить, что `modelina`/`redocly` принимают.

package/docs/usage.md

@@ -0,0 +1,281 @@
+# Использование `@tertiumorganum/typespec-amqp-ws`
+
+## Установка
+
+```bash
+npm install -D @tertiumorganum/typespec-amqp-ws @typespec/compiler @typespec/asset-emitter
+```
+
+Требования:
+- Node.js 22+ (рекомендуется 24+ для совместимости с `@asyncapi/cli`)
+- TypeSpec 1.12+
+
+## Конфигурация
+
+В корне папки с TypeSpec-описанием сервиса (например, `<service>/asyncapi/`) создаётся файл `tspconfig.yaml`. Эмиттер `@tertiumorganum/typespec-amqp-ws` имеет два emit-таргета: `/amqp` и `/ws`. Один проект использует **один** из них.
+
+### Конфиг для AMQP-сервиса
+
+```yaml
+emit:
+  - "@tertiumorganum/typespec-amqp-ws/amqp"
+options:
+  "@tertiumorganum/typespec-amqp-ws/amqp":
+    file-type: yaml          # yaml (default) или json
+    output-file: "asyncapi.yaml"
+    new-line: "lf"           # lf (default) или crlf
+output-dir: "{project-root}/tsp-output"
+```
+
+### Конфиг для WebSocket-сервиса
+
+```yaml
+emit:
+  - "@tertiumorganum/typespec-amqp-ws/ws"
+options:
+  "@tertiumorganum/typespec-amqp-ws/ws":
+    file-type: yaml
+    output-file: "asyncapi.yaml"
+    new-line: "lf"
+output-dir: "{project-root}/tsp-output"
+```
+
+После компиляции (`tsp compile .`) сгенерированный YAML лежит в `tsp-output/@tertiumorganum/typespec-amqp-ws/asyncapi.yaml`. Дальнейший пайплайн (redocly lint, modelina codegen, документация) идёт от этого файла.
+
+## Структура проекта
+
+Рекомендованная (соответствует тому, как у нас в команде):
+
+```
+<service>/asyncapi/
+├── main.tsp                     # @service / @info / @server + операции
+├── tsp-components/
+│   └── models.tsp               # scalars + enums + модели
+├── tspconfig.yaml               # конфиг эмиттера
+├── package.json                 # зависимости (typespec, asset-emitter)
+├── redocly.yaml                 # конфиг линтера
+└── Makefile                     # include шаблонного build pipeline
+```
+
+## API эмиттера
+
+### Декораторы общего назначения (namespace `TspAsyncApi`)
+
+| Декоратор | Применяется к | Что делает |
+|---|---|---|
+| `@service(#{title})` | namespace | Стандартный из `@typespec/compiler`. Маркирует namespace как корневой сервис. |
+| `@info(#{...})` | namespace | Заполняет блок `info:` AsyncAPI. Поля: `version`, `description?`, `contact?{name?, url?, email?}`, `license?{name, url?}`, `externalDocs?{url, description?}` |
+| `@server(name, #{...})` | namespace | Описывает один сервер (брокер). Поля: `host`, `protocol`, `pathname?`, `description?`, `variables?: Record<#{default?, description?, enum?}>` |
+
+### Декораторы AMQP (namespace `TspAsyncApi.Amqp`)
+
+| Декоратор | Применяется к | Описание |
+|---|---|---|
+| `@publish(#{...})` | op | Операция-publisher → `action: send`. Поля: `channelName?`, `routingKey?`, `exchange: #{name, type: "direct"\|"fanout", durable?, autoDelete?}` |
+| `@consume(#{...})` | op | Операция-consumer → `action: receive`. Поля: `channelName?`, `routingKey?`, `queue: #{name, durable?, autoDelete?, exclusive?}` |
+| `@message(#{...})` | op | Override параметров сообщения: `name?`, `summary?` |
+
+### Декораторы WebSocket (namespace `TspAsyncApi.WebSocket`)
+
+| Декоратор | Применяется к | Описание |
+|---|---|---|
+| `@publish` | op | без аргументов → `action: send` |
+| `@consume` | op | без аргументов → `action: receive` |
+| `@reply(MessageModel)` | op | Модель ответного сообщения (request/reply pattern). Reply-сообщение автоматически добавится в канал и `components.messages`. |
+| `@binary` | op | Помечает сообщение бинарным → `contentType: application/octet-stream` |
+| `@message(#{...})` | op | Override параметров сообщения |
+
+### Стандартные TypeSpec-декораторы
+
+Из `@typespec/compiler`:
+- `@doc("...")` — длинное описание (попадает в `description` YAML)
+- `@summary("...")` — короткое summary (попадает в `summary` YAML)
+
+## Поддерживаемые TypeSpec-типы
+
+| TypeSpec | YAML | Go / TS / C++ |
+|---|---|---|
+| `string` | `{type: string}` | string / string / std::string |
+| `boolean` | `{type: boolean}` | bool / boolean / bool |
+| `integer` | `{type: integer}` | int32 / number / int |
+| `bytes` | `{type: string, format: binary}` | []byte / Uint8Array / std::vector<uint8_t> |
+| `enum X { A, B }` | `{type: string, enum: [A, B]}` | string-typedef с константами |
+| `scalar X extends string` | `{type: string}` в `components.schemas.X` | именованный string-typedef |
+| `model X { ... }` | `{type: object, properties, required, additionalProperties: false}` | сгенерированная структура |
+| `T[]` | `{type: array, items: <T>}` | slice / array |
+| `Record<T>` | `{type: object, additionalProperties: <T>}` | `map[string]T` / `Record<string, T>` |
+| literal `"foo"` (на поле модели) | `{type: string, const: "foo"}` | const-значение |
+| `T \| null` | `{type: [<base>, null]}` | pointer / nullable |
+| `field?: T` | поле не в `required` | optional |
+
+## Запрещённые типы (ошибка компиляции)
+
+Эмиттер намеренно **запрещает**:
+
+| Тип | Почему |
+|---|---|
+| `int8`/`int16`/`int32`, `uint8`/`uint16`/`uint32` | Кодгенераторы (`modelina`, `openapi-generator-cli`) **игнорируют** ширину и signed/unsigned, генерируют `int32`/`number`. Размер-специфичные типы создают ложное ожидание сохранения семантики на границе между языками. |
+| `int64`/`uint64` | 64-битные числа должны передаваться как `string` — JavaScript не умеет точно представлять 64-битные числа в JSON. Поясните формат в `@doc`. |
+| `float32`/`float64`/`decimal`/`decimal128` | Числа с плавающей точкой передавайте через `string` во избежание потерь точности на границе между языками. |
+| `safeint`/`numeric` | Неоднозначно для кодогенерации. Используйте `integer`. |
+| `utcDateTime`/`plainDate`/`plainTime`/`duration` | Дата/время — это `string` в RFC-3339 с пояснением в `@doc`. TypeScript-кодген иначе подставляет `Date`, что ломает разбор в разных локалях. |
+| `url` | URL — это `string`. |
+
+Эмиттер также **запрещает анонимные inline-модели в полях**:
+
+```typespec
+// ❌ Ошибка эмиттера
+model M {
+  payload: { foo: string };
+}
+
+// ✅ Только через явно объявленную модель
+model MPayload { foo: string; }
+model M { payload: MPayload; }
+```
+
+Обоснование: детерминированные имена в выводе важнее лаконичности на стороне источника. modelina требует осмысленных имён для генерации Go/TS-типов; авто-генерация ненадёжна.
+
+## Полный пример: AMQP-сервис
+
+```typespec
+import "@tertiumorganum/typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications" })
+@info(#{
+  version: "1.0.0",
+  description: "Сервис рассылки уведомлений через RabbitMQ",
+})
+@server("rabbit", #{
+  host: "rabbit.example.com:5672",
+  pathname: "/notifications",
+  protocol: "amqp",
+  description: "RabbitMQ-сервер",
+})
+namespace Notifications;
+
+@doc("Уведомление пользователю")
+model Notification {
+  @doc("Идентификатор уведомления")
+  notificationId: string;
+
+  @doc("Текст уведомления")
+  text: string;
+}
+
+@publish(#{
+  routingKey: "notifications.created",
+  exchange: #{
+    name: "notifications-exchange",
+    type: "direct",
+    durable: true,
+  },
+})
+@summary("Опубликовать новое уведомление")
+op sendNotification(): Notification;
+
+@consume(#{
+  routingKey: "notifications.acknowledge",
+  queue: #{
+    name: "notifications-ack-queue",
+    durable: true,
+    autoDelete: false,
+  },
+})
+@summary("Обработать подтверждение доставки")
+op handleAck(): Notification;
+```
+
+## Полный пример: WebSocket с дискриминатором и reply
+
+```typespec
+import "@tertiumorganum/typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Chat WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{
+  host: "localhost:{port}",
+  protocol: "ws",
+  pathname: "/chat",
+  variables: #{
+    port: #{ `default`: "8080", description: "Порт WS-сервера" },
+  },
+})
+namespace Chat;
+
+// Дискриминатор сообщения — обычное поле literal-типа.
+// Эмиттер выведет {type: "string", const: "userJoined"} в JSON Schema.
+model UserJoined {
+  eventType: "userJoined";
+  msgUid: string;
+  userId: string;
+  nickname: string;
+}
+
+model SendMessage {
+  eventType: "sendMessage";
+  msgUid: string;
+  text: string;
+}
+
+model SendMessageResponse {
+  eventType: "sendMessageResponse";
+  msgUid: string;
+  ok: boolean;
+}
+
+// Receive
+@consume
+@summary("Пользователь подключился к чату")
+op userJoined(): UserJoined;
+
+// Send + reply (request/reply pattern)
+@publish
+@reply(SendMessageResponse)
+@summary("Отправить сообщение в чат")
+op sendMessage(): SendMessage;
+```
+
+Все WS-операции автоматически складываются на единый канал `/`. Это типичный паттерн WebSocket-API, где дискриминация сообщений происходит через поле `eventType`.
+
+## Версионирование AsyncAPI
+
+Эмиттер генерирует AsyncAPI 3.0.0. Версия 3.1 backward-совместима, но мы остаёмся на 3.0 ради консервативности и максимальной совместимости с `modelina`/`redocly`.
+
+## Дискриминация сообщений в WebSocket
+
+В TypeSpec литерал-типы (`"localActions"`) превращаются в JSON Schema `const` — нативный механизм без специальных декораторов. **Любое** поле модели типа `: "значение"` становится `const` в схеме. Поле может называться как угодно — `eventType`, `kind`, `type`, и т.д. Модели без таких полей тоже валидны (например, AMQP-сообщения обычно без дискриминатора).
+
+## Диагностики
+
+Эмиттер выдаёт следующие коды (все с префиксом `@tertiumorganum/typespec-amqp-ws/`):
+
+- `unsupported-sized-int`, `unsupported-int64`, `unsupported-float`, `unsupported-fuzzy-numeric`, `unsupported-temporal`, `unsupported-url` — попытка использовать запрещённый тип.
+- `anonymous-model`, `anonymous-return` — анонимная inline-модель в поле или return type.
+- `non-string-enum`, `invalid-enum-value` — некорректный enum (numeric или не-идентификаторное значение).
+- `unknown-exchange-type` — `topic` или `headers` exchange (вне scope).
+- `unsupported-union` — union, не являющийся `T | null`.
+- `missing-doc` (warning) — модель/enum без `@doc`.
+
+## Out of scope (v1)
+
+Намеренно **не реализовано** в v1 — добавляется по запросу при реальной потребности:
+
+- Транспорты Kafka, MQTT, HTTP/SSE, SNS/SQS.
+- Exchange types `topic`, `headers`.
+- AsyncAPI security schemes.
+- `correlationId`.
+- Traits (`channelTraits`, `operationTraits`, `messageTraits`).
+- AsyncAPI extensions (`x-` properties).
+- Polymorphism: пользовательские `oneOf`/`anyOf`/`allOf` (внутренний `allOf` для $ref+description — используется автоматически).
+- TypeSpec `@versioned` интеграция.
+- Numeric-валуированные enum.
+- `@tag` на operations.
+- AsyncAPI 3.1.
+- JSON output (только YAML).

package/examples/amqp-consume.tsp

@@ -0,0 +1,26 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications Consumer" })
+@info(#{ version: "1.0.0" })
+@server("rabbit", #{ host: "localhost:5672", protocol: "amqp" })
+namespace NotificationsConsumer;
+
+@doc("Уведомление пользователю")
+model Notification {
+  notificationId: string;
+  text: string;
+}
+
+@consume(#{
+  routingKey: "notifications.created",
+  queue: #{
+    name: "notifications-consumer-queue",
+    durable: true,
+    autoDelete: false,
+  },
+})
+@summary("Обработать уведомление из очереди")
+op handleNotification(): Notification;

package/examples/amqp-publish.tsp

@@ -0,0 +1,25 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.Amqp;
+
+@service(#{ title: "Notifications Producer" })
+@info(#{ version: "1.0.0" })
+@server("rabbit", #{ host: "localhost:5672", protocol: "amqp" })
+namespace NotificationsProducer;
+
+@doc("Уведомление пользователю")
+model Notification {
+  @doc("Уникальный идентификатор уведомления")
+  notificationId: string;
+
+  @doc("Текст уведомления")
+  text: string;
+}
+
+@publish(#{
+  routingKey: "notifications.created",
+  exchange: #{ name: "notifications-exchange", type: "direct", durable: true },
+})
+@summary("Опубликовать новое уведомление")
+op sendNotification(): Notification;

package/examples/ws-discriminator.tsp

@@ -0,0 +1,26 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Chat WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{ host: "localhost:8080", protocol: "ws", pathname: "/ws" })
+namespace Chat;
+
+model UserJoinedPayload { userId: string; nickname: string; }
+model MessagePayload { from: string; text: string; }
+
+// Дискриминатор через literal-тип — никаких специальных декораторов.
+model UserJoined {
+  eventType: "userJoined";
+  payload: UserJoinedPayload;
+}
+
+model NewMessage {
+  eventType: "newMessage";
+  payload: MessagePayload;
+}
+
+@consume op userJoined(): UserJoined;
+@consume op newMessage(): NewMessage;

package/examples/ws-reply.tsp

@@ -0,0 +1,29 @@
+import "typespec-amqp-ws";
+
+using TspAsyncApi;
+using TspAsyncApi.WebSocket;
+
+@service(#{ title: "Auth WS" })
+@info(#{ version: "1.0.0" })
+@server("public", #{ host: "localhost:8080", protocol: "ws", pathname: "/ws" })
+namespace Auth;
+
+model LoginRequestPayload { username: string; password: string; }
+model LoginResponsePayload { ok: boolean; token?: string; }
+
+model LoginRequest {
+  eventType: "loginRequest";
+  msgUid: string;
+  payload: LoginRequestPayload;
+}
+
+model LoginResponse {
+  eventType: "loginResponse";
+  msgUid: string;
+  payload: LoginResponsePayload;
+}
+
+@publish
+@reply(LoginResponse)
+@summary("Запрос на аутентификацию")
+op login(): LoginRequest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertiumorganum/typespec-amqp-ws",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "TypeSpec emitter for AsyncAPI 3.0 covering AMQP (RabbitMQ) and WebSocket transports",
   "license": "MIT",
   "type": "module",
@@ -51,6 +51,8 @@
   "files": [
     "dist/src/**",
     "lib/**",
+    "docs/**",
+    "examples/**",
     "README.md",
     "LICENSE"
   ]