@nxgt/typespec 0.1.0 → 0.3.0

package/README.md

@@ -292,10 +292,14 @@ interface Posts extends Resource<Post, PostFilters, SortField = "createdAt" | "t
 | Operation | Route | Answers |
 | --- | --- | --- |
 | `listPosts` | `GET /posts`, with the filters, `page`, `pageSize`, `orderBy`, `direction` | `Page<Post>` |
-| `readPosts` | `GET /posts/{id}` | `Post \| NotFound` |
-| `createPosts` | `POST /posts`, `Create<Post>` | 201 `Post \| BadRequest \| Conflict` |
-| `updatePosts` | `PATCH /posts/{id}`, `MergePatchUpdate<Post>` | `Post \| BadRequest \| NotFound \| Conflict` |
-| `deletePosts` | `DELETE /posts/{id}` | 204, `NotFound` |
+| `readPost` | `GET /posts/{id}` | `Post \| NotFound` |
+| `createPost` | `POST /posts`, `Create<Post>` | 201 `Post \| BadRequest \| Conflict` |
+| `updatePost` | `PATCH /posts/{id}`, `MergePatchUpdate<Post>` | `Post \| BadRequest \| NotFound \| Conflict` |
+| `deletePost` | `DELETE /posts/{id}` | 204, `NotFound` |
+
+`list` is named after the interface, the four others after the item. Two resources of one item then share their ids,
+which is an error, `duplicate-operation-id`: give the second its own
+`@operationId`s ([troubleshooting](docs/troubleshooting.md)).
 
 `orderBy` takes one of the `SortField`s (`SortField` is `"id"` by default), and `direction`
 `asc` (the default) or `desc`, as `@nxgt/drizzle` sorts a page. `{id}`
@@ -336,6 +340,14 @@ of a marked interface that has another operation's id is an error,
 | --- | --- | --- |
 | `@operationIds` | an interface | names each operation `<operation><Interface>`, unless it has an `@operationId` |
 
+### Diagnostics
+
+| Code | Reported when |
+| --- | --- |
+| `duplicate-operation-id` | error: an operation of an `@operationIds` interface has another operation's id |
+| `duplicate-status-reply` | error: an operation declares a reply without a body and one with a body of one status, which the emitter merges, losing the one without a body |
+| `merged-status-reply` | warning: an operation declares two replies with a body of one status code, which the emitter merges under the first one's description |
+
 ### Models
 
 | Model | What it is |
@@ -415,14 +427,17 @@ envelope and the rate limit's headers.
     @body body: ServiceUnavailableBody;
   }
   ```
-- **One status, one reply.** An operation that declares both
-  `AuthenticationRequired` and `Unauthorized` gets a single 401, with the
-  envelope: the reply without a body is lost, without a warning. Declare the
-  one the route sends: the guard's, or the handler's. The same goes for
-  `Conflict` beside `IdempotencyInProgress`, and `UnprocessableEntity`
-  beside `IdempotencyKeyReused`: both keep one body, but the reply's
-  description is the first one's, and the body a union of the envelope with
-  itself. Declare one of each pair: the `message` key tells them apart.
+- **One status, one reply.** `@typespec/openapi3` merges two replies of one
+  status into one. With `AuthenticationRequired` and `Unauthorized`, the 401
+  keeps the envelope and the reply without a body is lost: the library
+  refuses it, `duplicate-status-reply`. With `Conflict` beside
+  `IdempotencyInProgress`, or `UnprocessableEntity` beside
+  `IdempotencyKeyReused`, both bodies stay, under the first reply's
+  description: the library warns, `merged-status-reply`. Declare the one the
+  route sends; for the idempotent write, the `message` key tells them apart.
+  Two plain bodies, `Post | Draft`, bodies of different content types, and
+  two `@error` models without a `@statusCode` pass
+  ([troubleshooting](docs/troubleshooting.md)).
 - **Both versions at once write two folders.** With
   `openapi-versions: ['3.1.0', '3.2.0']`, the emitter writes
   `3.1.0/openapi.yaml` and `3.2.0/openapi.yaml`: point the generator's input

package/dist/index.d.ts

@@ -7,12 +7,15 @@
  * export would declare it a second time, in the global namespace.
  */
 import type { Program } from '@typespec/compiler';
-import { operationIds } from './operation-ids';
+import { itemOperation, operationIds } from './operation-ids';
 export { $lib } from './lib';
 export declare function $onValidate(program: Program): void;
 export declare const $decorators: {
     Nxgt: {
         operationIds: typeof operationIds;
     };
+    'Nxgt.Private': {
+        itemOperation: typeof itemOperation;
+    };
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAE7B,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,eAAO,MAAM,WAAW;;;;CAEvB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EACN,aAAa,EACb,YAAY,EAEZ,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAE7B,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGlD;AAED,eAAO,MAAM,WAAW;;;;;;;CAGvB,CAAC"}

package/dist/index.js

@@ -1,13 +1,8 @@
-// src/operation-ids.ts
-import {
-  isTemplateInstance,
-  navigateProgram
-} from "@typespec/compiler";
+// src/one-reply-per-status.ts
+import { isVoidType } from "@typespec/compiler";
 import {
-  getOperationId,
-  resolveOperationId,
-  setOperationId
-} from "@typespec/openapi";
+  getAllHttpServices
+} from "@typespec/http";
 
 // src/lib.ts
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
@@ -19,17 +14,99 @@ var $lib = createTypeSpecLibrary({
       messages: {
         default: paramMessage`Two operations are named ${"id"}: an OpenAPI operation id must be unique.`
       }
+    },
+    "duplicate-status-reply": {
+      severity: "error",
+      messages: {
+        default: paramMessage`${"operation"} declares a reply without a body and one with a body of status ${"status"}: the emitter merges them into one, and the reply without a body is lost. Declare the one the route sends.`
+      }
+    },
+    "merged-status-reply": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`${"operation"} declares two replies with a body of status ${"status"}: the emitter merges their bodies under the first one's description. Declare the one the route sends.`
+      }
     }
   },
   state: {
-    operationIds: { description: "The interfaces marked with @operationIds" }
+    operationIds: { description: "The interfaces marked with @operationIds" },
+    itemOperations: {
+      description: "The operations named after an item, and the item's model"
+    }
   }
 });
 
+// src/one-reply-per-status.ts
+function statusOf(code) {
+  return typeof code === "object" ? `${code.start}-${code.end}` : `${code}`;
+}
+function mergeOf({
+  statusCodes,
+  responses
+}) {
+  const bodies = responses.flatMap(({ body }) => body && !isVoidType(body.type) ? [body] : []);
+  if (bodies.length > 0 && bodies.length < responses.length) {
+    return "duplicate-status-reply";
+  }
+  if (typeof statusCodes !== "number")
+    return;
+  const seen = new Set;
+  for (const body of bodies) {
+    if (body.contentTypes.some((type) => seen.has(type))) {
+      return "merged-status-reply";
+    }
+    for (const type of body.contentTypes)
+      seen.add(type);
+  }
+  return;
+}
+function validateOneReplyPerStatus(program) {
+  const [services] = getAllHttpServices(program);
+  const checked = new Set;
+  for (const service of services) {
+    for (const operation of service.operations) {
+      if (checked.has(operation.operation))
+        continue;
+      checked.add(operation.operation);
+      for (const response of operation.responses) {
+        const code = mergeOf(response);
+        if (code === undefined)
+          continue;
+        $lib.reportDiagnostic(program, {
+          code,
+          format: {
+            operation: operation.operation.name,
+            status: statusOf(response.statusCodes)
+          },
+          target: operation.operation
+        });
+      }
+    }
+  }
+}
+
 // src/operation-ids.ts
+import {
+  getFriendlyName,
+  isTemplateInstance,
+  navigateProgram
+} from "@typespec/compiler";
+import {
+  getOperationId,
+  resolveOperationId,
+  setOperationId
+} from "@typespec/openapi";
 function operationIds(context, target) {
   context.program.stateSet($lib.stateKeys.operationIds).add(target);
 }
+function itemOperation(context, target, item) {
+  context.program.stateMap($lib.stateKeys.itemOperations).set(target, item);
+}
+function nounOf(program, operation) {
+  const item = program.stateMap($lib.stateKeys.itemOperations).get(operation);
+  const named = item && (getFriendlyName(program, item) ?? (item.name !== "" && !isTemplateInstance(item) ? item.name : undefined));
+  return named ?? operation.interface?.name;
+}
 function isMarked(program, target) {
   return program.stateSet($lib.stateKeys.operationIds).has(target) || target.sourceInterfaces.some((source) => isMarked(program, source));
 }
@@ -43,7 +120,7 @@ function validateOperationIds(program) {
     operation(operation) {
       const named = isNamed(program, operation);
       const own = getOperationId(program, operation);
-      const id = own ?? (named ? `${operation.name}${operation.interface?.name}` : resolveOperationId(program, operation));
+      const id = own ?? (named ? `${operation.name}${nounOf(program, operation)}` : resolveOperationId(program, operation));
       if (seen.has(id) && (named || seen.get(id))) {
         $lib.reportDiagnostic(program, {
           code: "duplicate-operation-id",
@@ -61,9 +138,11 @@ function validateOperationIds(program) {
 // src/index.ts
 function $onValidate(program) {
   validateOperationIds(program);
+  validateOneReplyPerStatus(program);
 }
 var $decorators = {
-  Nxgt: { operationIds }
+  Nxgt: { operationIds },
+  "Nxgt.Private": { itemOperation }
 };
 export {
   $decorators,
@@ -71,5 +150,5 @@ export {
   $onValidate
 };
 
-//# debugId=2D92CF45DEECB16A64756E2164756E21
+//# debugId=D1BB8C6D97A7E43C64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,12 +1,13 @@
 {
   "version": 3,
-  "sources": ["../src/operation-ids.ts", "../src/lib.ts", "../src/index.ts"],
+  "sources": ["../src/one-reply-per-status.ts", "../src/lib.ts", "../src/operation-ids.ts", "../src/index.ts"],
   "sourcesContent": [
-    "/**\n * `@operationIds`: names each operation of an interface after its method and\n * the interface, `<operation><Interface>`, such as `listPets`.\n */\nimport {\n\ttype DecoratorContext,\n\ttype Interface,\n\tisTemplateInstance,\n\tnavigateProgram,\n\ttype Operation,\n\ttype Program,\n} from '@typespec/compiler';\nimport {\n\tgetOperationId,\n\tresolveOperationId,\n\tsetOperationId,\n} from '@typespec/openapi';\nimport { $lib } from './lib';\n\n/**\n * Marks the interface; its ids are set once the program is checked. On a\n * template, TypeSpec runs it on each instance, which `isMarked` follows to\n * the interfaces extending it.\n */\nexport function operationIds(\n\tcontext: DecoratorContext,\n\ttarget: Interface,\n): void {\n\tcontext.program.stateSet($lib.stateKeys.operationIds).add(target);\n}\n\n/** Marked itself, or extending a marked interface: an instance of a marked template included. */\nfunction isMarked(program: Program, target: Interface): boolean {\n\treturn (\n\t\tprogram.stateSet($lib.stateKeys.operationIds).has(target) ||\n\t\ttarget.sourceInterfaces.some((source) => isMarked(program, source))\n\t);\n}\n\n/**\n * Whether `@operationIds` names the operation's id, or checks it: its\n * interface is marked, and is not a template instance, which is never\n * emitted; only the interfaces extending it are.\n */\nfunction isNamed(program: Program, operation: Operation): boolean {\n\tconst container = operation.interface;\n\treturn (\n\t\tcontainer !== undefined &&\n\t\t!isTemplateInstance(container) &&\n\t\tisMarked(program, container)\n\t);\n}\n\n/**\n * Sets the ids, after every decorator, so the order of `@operationId` and\n * `@operationIds` in the source does not matter. Two operations with one id,\n * one of them in a marked interface, are an error: two interfaces of one name\n * in two namespaces, an `@operationId` that `extends` copied, one written\n * elsewhere, or an operation in the service namespace, named after itself. `@typespec/openapi3` would emit both without a word.\n */\nexport function validateOperationIds(program: Program): void {\n\tconst seen = new Map<string, boolean>();\n\tnavigateProgram(program, {\n\t\toperation(operation) {\n\t\t\tconst named = isNamed(program, operation);\n\t\t\tconst own = getOperationId(program, operation);\n\t\t\t// Elsewhere, only checked: the id `@typespec/openapi3` gives under its\n\t\t\t// default strategy; an operation in the service namespace is named\n\t\t\t// after itself.\n\t\t\tconst id =\n\t\t\t\town ??\n\t\t\t\t(named\n\t\t\t\t\t? `${operation.name}${operation.interface?.name}`\n\t\t\t\t\t: resolveOperationId(program, operation));\n\t\t\tif (seen.has(id) && (named || seen.get(id))) {\n\t\t\t\t$lib.reportDiagnostic(program, {\n\t\t\t\t\tcode: 'duplicate-operation-id',\n\t\t\t\t\tformat: { id },\n\t\t\t\t\ttarget: operation,\n\t\t\t\t});\n\t\t\t}\n\t\t\tseen.set(id, named || (seen.get(id) ?? false));\n\t\t\t// Only the ids it gives: an explicit id on any other operation would\n\t\t\t// override the emitter's `operation-id-strategy`.\n\t\t\tif (named && own === undefined) setOperationId(program, operation, id);\n\t\t},\n\t});\n}\n",
-    "/** The library's definition: its name, diagnostics and state keys. */\nimport { createTypeSpecLibrary, paramMessage } from '@typespec/compiler';\n\nexport const $lib = createTypeSpecLibrary({\n\tname: '@nxgt/typespec',\n\tdiagnostics: {\n\t\t'duplicate-operation-id': {\n\t\t\tseverity: 'error',\n\t\t\tmessages: {\n\t\t\t\tdefault: paramMessage`Two operations are named ${'id'}: an OpenAPI operation id must be unique.`,\n\t\t\t},\n\t\t},\n\t},\n\tstate: {\n\t\toperationIds: { description: 'The interfaces marked with @operationIds' },\n\t},\n});\n",
-    "/**\n * The JavaScript side of the `@nxgt/typespec` library, which `lib/main.tsp`\n * imports from `dist/`: its name and diagnostics, and the decorators a\n * template cannot express. The conventions themselves are in `lib/`.\n *\n * A decorator is exported only through `$decorators`: a top-level `$name`\n * export would declare it a second time, in the global namespace.\n */\nimport type { Program } from '@typespec/compiler';\nimport { operationIds, validateOperationIds } from './operation-ids';\n\nexport { $lib } from './lib';\n\nexport function $onValidate(program: Program): void {\n\tvalidateOperationIds(program);\n}\n\nexport const $decorators = {\n\tNxgt: { operationIds },\n};\n"
+    "/**\n * One reply per status: `@typespec/openapi3` merges two replies of one\n * status into one without a word. A reply without a body beside one with a\n * body is lost in the merge, an error; a `void` body is none, as the emitter\n * sees it. Two bodies of one content type are merged under the first reply's\n * description, a warning where the status is a code. Under `*` or a range,\n * where undocumented `@error` models share one description, they pass.\n * Bodies of different content types are one reply, negotiated, and pass.\n */\nimport { isVoidType, type Operation, type Program } from '@typespec/compiler';\nimport {\n\tgetAllHttpServices,\n\ttype HttpOperationResponse,\n\ttype HttpStatusCodesEntry,\n} from '@typespec/http';\nimport { $lib } from './lib';\n\nfunction statusOf(code: HttpStatusCodesEntry): string {\n\treturn typeof code === 'object' ? `${code.start}-${code.end}` : `${code}`;\n}\n\n/** What the emitter's merge costs: a reply, a description, or nothing. */\nfunction mergeOf({\n\tstatusCodes,\n\tresponses,\n}: HttpOperationResponse):\n\t| 'duplicate-status-reply'\n\t| 'merged-status-reply'\n\t| undefined {\n\tconst bodies = responses.flatMap(({ body }) =>\n\t\tbody && !isVoidType(body.type) ? [body] : [],\n\t);\n\tif (bodies.length > 0 && bodies.length < responses.length) {\n\t\treturn 'duplicate-status-reply';\n\t}\n\tif (typeof statusCodes !== 'number') return undefined;\n\tconst seen = new Set<string>();\n\tfor (const body of bodies) {\n\t\tif (body.contentTypes.some((type) => seen.has(type))) {\n\t\t\treturn 'merged-status-reply';\n\t\t}\n\t\tfor (const type of body.contentTypes) seen.add(type);\n\t}\n\treturn undefined;\n}\n\n/**\n * Checks each operation of each service, as the emitter sees it, once: a\n * service nested in another is listed in both. The services' own\n * diagnostics are the emitter's to report.\n */\nexport function validateOneReplyPerStatus(program: Program): void {\n\tconst [services] = getAllHttpServices(program);\n\tconst checked = new Set<Operation>();\n\tfor (const service of services) {\n\t\tfor (const operation of service.operations) {\n\t\t\tif (checked.has(operation.operation)) continue;\n\t\t\tchecked.add(operation.operation);\n\t\t\tfor (const response of operation.responses) {\n\t\t\t\tconst code = mergeOf(response);\n\t\t\t\tif (code === undefined) continue;\n\t\t\t\t$lib.reportDiagnostic(program, {\n\t\t\t\t\tcode,\n\t\t\t\t\tformat: {\n\t\t\t\t\t\toperation: operation.operation.name,\n\t\t\t\t\t\tstatus: statusOf(response.statusCodes),\n\t\t\t\t\t},\n\t\t\t\t\ttarget: operation.operation,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n}\n",
+    "/** The library's definition: its name, diagnostics and state keys. */\nimport { createTypeSpecLibrary, paramMessage } from '@typespec/compiler';\n\nexport const $lib = createTypeSpecLibrary({\n\tname: '@nxgt/typespec',\n\tdiagnostics: {\n\t\t'duplicate-operation-id': {\n\t\t\tseverity: 'error',\n\t\t\tmessages: {\n\t\t\t\tdefault: paramMessage`Two operations are named ${'id'}: an OpenAPI operation id must be unique.`,\n\t\t\t},\n\t\t},\n\t\t'duplicate-status-reply': {\n\t\t\tseverity: 'error',\n\t\t\tmessages: {\n\t\t\t\tdefault: paramMessage`${'operation'} declares a reply without a body and one with a body of status ${'status'}: the emitter merges them into one, and the reply without a body is lost. Declare the one the route sends.`,\n\t\t\t},\n\t\t},\n\t\t'merged-status-reply': {\n\t\t\tseverity: 'warning',\n\t\t\tmessages: {\n\t\t\t\tdefault: paramMessage`${'operation'} declares two replies with a body of status ${'status'}: the emitter merges their bodies under the first one's description. Declare the one the route sends.`,\n\t\t\t},\n\t\t},\n\t},\n\tstate: {\n\t\toperationIds: { description: 'The interfaces marked with @operationIds' },\n\t\titemOperations: {\n\t\t\tdescription: \"The operations named after an item, and the item's model\",\n\t\t},\n\t},\n});\n",
+    "/**\n * `@operationIds`: names each operation of an interface after its method and\n * the interface, `<operation><Interface>`, such as `listPets`.\n */\nimport {\n\ttype DecoratorContext,\n\tgetFriendlyName,\n\ttype Interface,\n\tisTemplateInstance,\n\ttype Model,\n\tnavigateProgram,\n\ttype Operation,\n\ttype Program,\n} from '@typespec/compiler';\nimport {\n\tgetOperationId,\n\tresolveOperationId,\n\tsetOperationId,\n} from '@typespec/openapi';\nimport { $lib } from './lib';\n\n/**\n * Marks the interface; its ids are set once the program is checked. On a\n * template, TypeSpec runs it on each instance, which `isMarked` follows to\n * the interfaces extending it.\n */\nexport function operationIds(\n\tcontext: DecoratorContext,\n\ttarget: Interface,\n): void {\n\tcontext.program.stateSet($lib.stateKeys.operationIds).add(target);\n}\n\n/**\n * Names the operation after one item, `<operation><Item>`, instead of its\n * interface, where `@operationIds` names it: `Resource` marks `read`,\n * `create`, `update` and `delete`, so `Authors` has `readAuthor`, but\n * `listAuthors`. Not public: `Resource`'s alone.\n */\nexport function itemOperation(\n\tcontext: DecoratorContext,\n\ttarget: Operation,\n\titem: Model,\n): void {\n\tcontext.program.stateMap($lib.stateKeys.itemOperations).set(target, item);\n}\n\n/**\n * The name `@operationIds` puts after the operation's: its item's, or its\n * interface's. An item without a name of its own, anonymous or an instance\n * such as `Versioned<Author>`, whose name would be `Versioned` alone, falls\n * back to the interface.\n */\nfunction nounOf(program: Program, operation: Operation): string | undefined {\n\tconst item: Model | undefined = program\n\t\t.stateMap($lib.stateKeys.itemOperations)\n\t\t.get(operation);\n\tconst named =\n\t\titem &&\n\t\t(getFriendlyName(program, item) ??\n\t\t\t(item.name !== '' && !isTemplateInstance(item) ? item.name : undefined));\n\treturn named ?? operation.interface?.name;\n}\n\n/** Marked itself, or extending a marked interface: an instance of a marked template included. */\nfunction isMarked(program: Program, target: Interface): boolean {\n\treturn (\n\t\tprogram.stateSet($lib.stateKeys.operationIds).has(target) ||\n\t\ttarget.sourceInterfaces.some((source) => isMarked(program, source))\n\t);\n}\n\n/**\n * Whether `@operationIds` names the operation's id, or checks it: its\n * interface is marked, and is not a template instance, which is never\n * emitted; only the interfaces extending it are.\n */\nfunction isNamed(program: Program, operation: Operation): boolean {\n\tconst container = operation.interface;\n\treturn (\n\t\tcontainer !== undefined &&\n\t\t!isTemplateInstance(container) &&\n\t\tisMarked(program, container)\n\t);\n}\n\n/**\n * Sets the ids, after every decorator, so the order of `@operationId` and\n * `@operationIds` in the source does not matter. Two operations with one id,\n * one of them in a marked interface, are an error: two interfaces of one name\n * in two namespaces, an `@operationId` that `extends` copied, one written\n * elsewhere, or an operation in the service namespace, named after itself. `@typespec/openapi3` would emit both without a word.\n */\nexport function validateOperationIds(program: Program): void {\n\tconst seen = new Map<string, boolean>();\n\tnavigateProgram(program, {\n\t\toperation(operation) {\n\t\t\tconst named = isNamed(program, operation);\n\t\t\tconst own = getOperationId(program, operation);\n\t\t\t// Elsewhere, only checked: the id `@typespec/openapi3` gives under its\n\t\t\t// default strategy; an operation in the service namespace is named\n\t\t\t// after itself.\n\t\t\tconst id =\n\t\t\t\town ??\n\t\t\t\t(named\n\t\t\t\t\t? `${operation.name}${nounOf(program, operation)}`\n\t\t\t\t\t: resolveOperationId(program, operation));\n\t\t\tif (seen.has(id) && (named || seen.get(id))) {\n\t\t\t\t$lib.reportDiagnostic(program, {\n\t\t\t\t\tcode: 'duplicate-operation-id',\n\t\t\t\t\tformat: { id },\n\t\t\t\t\ttarget: operation,\n\t\t\t\t});\n\t\t\t}\n\t\t\tseen.set(id, named || (seen.get(id) ?? false));\n\t\t\t// Only the ids it gives: an explicit id on any other operation would\n\t\t\t// override the emitter's `operation-id-strategy`.\n\t\t\tif (named && own === undefined) setOperationId(program, operation, id);\n\t\t},\n\t});\n}\n",
+    "/**\n * The JavaScript side of the `@nxgt/typespec` library, which `lib/main.tsp`\n * imports from `dist/`: its name and diagnostics, and the decorators a\n * template cannot express. The conventions themselves are in `lib/`.\n *\n * A decorator is exported only through `$decorators`: a top-level `$name`\n * export would declare it a second time, in the global namespace.\n */\nimport type { Program } from '@typespec/compiler';\nimport { validateOneReplyPerStatus } from './one-reply-per-status';\nimport {\n\titemOperation,\n\toperationIds,\n\tvalidateOperationIds,\n} from './operation-ids';\n\nexport { $lib } from './lib';\n\nexport function $onValidate(program: Program): void {\n\tvalidateOperationIds(program);\n\tvalidateOneReplyPerStatus(program);\n}\n\nexport const $decorators = {\n\tNxgt: { operationIds },\n\t'Nxgt.Private': { itemOperation },\n};\n"
   ],
-  "mappings": ";AAIA;AAAA;AAAA;AAAA;AAQA;AAAA;AAAA;AAAA;AAAA;;;ACXA;AAEO,IAAM,OAAO,sBAAsB;AAAA,EACzC,MAAM;AAAA,EACN,aAAa;AAAA,IACZ,0BAA0B;AAAA,MACzB,UAAU;AAAA,MACV,UAAU;AAAA,QACT,SAAS,wCAAwC;AAAA,MAClD;AAAA,IACD;AAAA,EACD;AAAA,EACA,OAAO;AAAA,IACN,cAAc,EAAE,aAAa,2CAA2C;AAAA,EACzE;AACD,CAAC;;;ADQM,SAAS,YAAY,CAC3B,SACA,QACO;AAAA,EACP,QAAQ,QAAQ,SAAS,KAAK,UAAU,YAAY,EAAE,IAAI,MAAM;AAAA;AAIjE,SAAS,QAAQ,CAAC,SAAkB,QAA4B;AAAA,EAC/D,OACC,QAAQ,SAAS,KAAK,UAAU,YAAY,EAAE,IAAI,MAAM,KACxD,OAAO,iBAAiB,KAAK,CAAC,WAAW,SAAS,SAAS,MAAM,CAAC;AAAA;AASpE,SAAS,OAAO,CAAC,SAAkB,WAA+B;AAAA,EACjE,MAAM,YAAY,UAAU;AAAA,EAC5B,OACC,cAAc,aACd,CAAC,mBAAmB,SAAS,KAC7B,SAAS,SAAS,SAAS;AAAA;AAWtB,SAAS,oBAAoB,CAAC,SAAwB;AAAA,EAC5D,MAAM,OAAO,IAAI;AAAA,EACjB,gBAAgB,SAAS;AAAA,IACxB,SAAS,CAAC,WAAW;AAAA,MACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS;AAAA,MACxC,MAAM,MAAM,eAAe,SAAS,SAAS;AAAA,MAI7C,MAAM,KACL,QACC,QACE,GAAG,UAAU,OAAO,UAAU,WAAW,SACzC,mBAAmB,SAAS,SAAS;AAAA,MACzC,IAAI,KAAK,IAAI,EAAE,MAAM,SAAS,KAAK,IAAI,EAAE,IAAI;AAAA,QAC5C,KAAK,iBAAiB,SAAS;AAAA,UAC9B,MAAM;AAAA,UACN,QAAQ,EAAE,GAAG;AAAA,UACb,QAAQ;AAAA,QACT,CAAC;AAAA,MACF;AAAA,MACA,KAAK,IAAI,IAAI,UAAU,KAAK,IAAI,EAAE,KAAK,MAAM;AAAA,MAG7C,IAAI,SAAS,QAAQ;AAAA,QAAW,eAAe,SAAS,WAAW,EAAE;AAAA;AAAA,EAEvE,CAAC;AAAA;;;AEzEK,SAAS,WAAW,CAAC,SAAwB;AAAA,EACnD,qBAAqB,OAAO;AAAA;AAGtB,IAAM,cAAc;AAAA,EAC1B,MAAM,EAAE,aAAa;AACtB;",
-  "debugId": "2D92CF45DEECB16A64756E2164756E21",
+  "mappings": "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",
+  "debugId": "D1BB8C6D97A7E43C64756E2164756E21",
   "names": []
 }

package/dist/lib.d.ts

@@ -2,5 +2,11 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     'duplicate-operation-id': {
         readonly default: import("@typespec/compiler").CallableMessage<["id"]>;
     };
-}, Record<string, any>, "operationIds">;
+    'duplicate-status-reply': {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "status"]>;
+    };
+    'merged-status-reply': {
+        readonly default: import("@typespec/compiler").CallableMessage<["operation", "status"]>;
+    };
+}, Record<string, any>, "operationIds" | "itemOperations">;
 //# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,IAAI;;;;uCAaf,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,IAAI;;;;;;;;;;0DA4Bf,CAAC"}

package/dist/one-reply-per-status.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One reply per status: `@typespec/openapi3` merges two replies of one
+ * status into one without a word. A reply without a body beside one with a
+ * body is lost in the merge, an error; a `void` body is none, as the emitter
+ * sees it. Two bodies of one content type are merged under the first reply's
+ * description, a warning where the status is a code. Under `*` or a range,
+ * where undocumented `@error` models share one description, they pass.
+ * Bodies of different content types are one reply, negotiated, and pass.
+ */
+import { type Program } from '@typespec/compiler';
+/**
+ * Checks each operation of each service, as the emitter sees it, once: a
+ * service nested in another is listed in both. The services' own
+ * diagnostics are the emitter's to report.
+ */
+export declare function validateOneReplyPerStatus(program: Program): void;
+//# sourceMappingURL=one-reply-per-status.d.ts.map

package/dist/one-reply-per-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"one-reply-per-status.d.ts","sourceRoot":"","sources":["../src/one-reply-per-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAqC9E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBhE"}

package/dist/operation-ids.d.ts

@@ -2,13 +2,20 @@
  * `@operationIds`: names each operation of an interface after its method and
  * the interface, `<operation><Interface>`, such as `listPets`.
  */
-import { type DecoratorContext, type Interface, type Program } from '@typespec/compiler';
+import { type DecoratorContext, type Interface, type Model, type Operation, type Program } from '@typespec/compiler';
 /**
  * Marks the interface; its ids are set once the program is checked. On a
  * template, TypeSpec runs it on each instance, which `isMarked` follows to
  * the interfaces extending it.
  */
 export declare function operationIds(context: DecoratorContext, target: Interface): void;
+/**
+ * Names the operation after one item, `<operation><Item>`, instead of its
+ * interface, where `@operationIds` names it: `Resource` marks `read`,
+ * `create`, `update` and `delete`, so `Authors` has `readAuthor`, but
+ * `listAuthors`. Not public: `Resource`'s alone.
+ */
+export declare function itemOperation(context: DecoratorContext, target: Operation, item: Model): void;
 /**
  * Sets the ids, after every decorator, so the order of `@operationId` and
  * `@operationIds` in the source does not matter. Two operations with one id,

package/dist/operation-ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-ids.d.ts","sourceRoot":"","sources":["../src/operation-ids.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,SAAS,EAId,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAQ5B;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,GACf,IAAI,CAEN;AAwBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2B3D"}
+{"version":3,"file":"operation-ids.d.ts","sourceRoot":"","sources":["../src/operation-ids.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,KAAK,gBAAgB,EAErB,KAAK,SAAS,EAEd,KAAK,KAAK,EAEV,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAQ5B;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,GACf,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,KAAK,GACT,IAAI,CAEN;AAyCD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2B3D"}

package/docs/guide/auth.md

@@ -97,7 +97,7 @@ operation can declare the guard's 401 and the handler's 403:
 } | BadRequest | AuthenticationRequired | Forbidden;
 ```
 
-Not both replies of one status, though: an operation that declares
-`AuthenticationRequired` and `Unauthorized` gets a single 401, with the
-envelope, and the reply without a body is lost without a warning. Declare
-the one the route sends.
+Not both replies of one status, though: the emitter would merge
+`AuthenticationRequired` and `Unauthorized` into a single 401, with the
+envelope, and lose the reply without a body. The library refuses it with
+`duplicate-status-reply`: declare the one the route sends.

package/docs/guide/headers.md

@@ -41,8 +41,9 @@ interface Posts {
 
 Both carry the `RateLimit-*` headers, as a route that also has a rate limit
 answers them. An operation that declares `Conflict` too, for its optimistic
-lock, gets one 409 with the description of the first: declare one of the
-two, and tell them apart by the `message` key.
+lock, gets one 409 with the description of the first, and the library warns,
+`merged-status-reply`: declare one of the two, and tell them apart by the
+`message` key ([troubleshooting](../troubleshooting.md)).
 
 ## A rate limit
 

package/docs/guide/operation-ids.md

@@ -84,9 +84,13 @@ interface Pets extends Resource<Pet> {}     // listPets
 interface Orders extends Resource<Order> {} // listOrders
 ```
 
+The library's own `Resource` goes one step further: `list` is named after
+the interface, and `read`, `create`, `update` and `delete` after the item,
+`readPet` ([Resources](resources.md)).
+
 ## Two operations named alike
 
-An id must be unique, and four cases break that:
+An id must be unique, and five cases break that:
 
 - the namespace is not part of the id, so `Store.Pets` and `Shelter.Pets`
   would both name their `list` `listPets`;
@@ -95,7 +99,10 @@ An id must be unique, and four cases break that:
 - an `@operationId` written on another operation, in any interface, takes
   the id `@operationIds` gives;
 - an operation declared in the service namespace is named after itself, so
-  `op listPets()` takes the id of `Pets.list`.
+  `op listPets()` takes the id of `Pets.list`;
+- two interfaces extend `Resource` with one item, so `Authors` and
+  `ArchivedAuthors` would both name their `read` `readAuthor`
+  ([Resources](resources.md#two-resources-of-one-item)).
 
 `@operationIds` refuses each with `duplicate-operation-id`, where
 `@typespec/openapi3` would emit both without a word. Give one of them its own

package/docs/guide/resources.md

@@ -33,14 +33,55 @@ interface Authors extends Resource<Author, AuthorFilters, SortField = "name" | "
 | Operation | Route | Body | Answers |
 | --- | --- | --- | --- |
 | `listAuthors` | `GET /authors` | | `Page<Author>` |
-| `readAuthors` | `GET /authors/{id}` | | `Author`, `NotFound` |
-| `createAuthors` | `POST /authors` | `Create<Author>` | 201 `Author`, `BadRequest`, `Conflict` |
-| `updateAuthors` | `PATCH /authors/{id}` | `MergePatchUpdate<Author>` | `Author`, `BadRequest`, `NotFound`, `Conflict` |
-| `deleteAuthors` | `DELETE /authors/{id}` | | 204, `NotFound` |
+| `readAuthor` | `GET /authors/{id}` | | `Author`, `NotFound` |
+| `createAuthor` | `POST /authors` | `Create<Author>` | 201 `Author`, `BadRequest`, `Conflict` |
+| `updateAuthor` | `PATCH /authors/{id}` | `MergePatchUpdate<Author>` | `Author`, `BadRequest`, `NotFound`, `Conflict` |
+| `deleteAuthor` | `DELETE /authors/{id}` | | 204, `NotFound` |
+
+The template carries `@operationIds`. `list` is named after the interface
+that extends it, which holds the many, and `read`, `create`, `update` and
+`delete` after `Item`, the one: `listAuthors`, `readAuthor`. The item's
+name is its `@friendlyName`, if it has one. An item without a name of its
+own, an anonymous model or an instance such as `Draft<Author>`, falls back to
+the interface: `readDrafts`. An operation the extending interface declares
+again is named after the interface too, unless it has its own `@operationId`. The generated `operations` has
+one entry per id:
 
-The template carries `@operationIds`, so each operation is named after the
-interface that extends it. The generator's own 400 is on every operation
-that takes a parameter or a body, as always.
+```ts
+import { operations } from './generated/operations';
+
+Object.keys(operations);
+// ['listAuthors', 'createAuthor', 'readAuthor', 'updateAuthor', 'deleteAuthor']
+```
+
+The generator's own 400 is on every operation that takes a parameter or a
+body, as always.
+
+## Two resources of one item
+
+Two interfaces extending `Resource` with one `Item` share `readAuthor`,
+`createAuthor`, `updateAuthor` and `deleteAuthor`, which is an error,
+`duplicate-operation-id`. Declare the operations of the second again, each
+with its own `@operationId`, as an interface that extends overrides the
+template's. Use the resource's `Id` in place of `uuid`, if it names one:
+
+```tsp
+import "@typespec/openapi";
+
+using OpenAPI;
+
+@route("/archived-authors")
+interface ArchivedAuthors extends Resource<Author> {
+  @get @operationId("readArchivedAuthor") read(@path id: uuid): Author | NotFound;
+  @post @operationId("createArchivedAuthor") create(@body item: Create<Author>): {
+    @statusCode _: 201;
+    @body item: Author;
+  } | BadRequest | Conflict;
+  @patch @operationId("updateArchivedAuthor")
+  update(@path id: uuid, @body item: MergePatchUpdate<Author>): Author | BadRequest | NotFound | Conflict;
+  @delete @operationId("deleteArchivedAuthor") delete(@path id: uuid): NoContentResponse | NotFound;
+}
+```
 
 ## The template's arguments
 
@@ -110,3 +151,7 @@ interface Comments extends Resource<Comment> {
 Add `@useAuth(JanusAuth)` on the interface to protect all five, and name the
 guards' replies in the operations you declare again
 ([Authentication](auth.md)).
+
+A `read`, `create`, `update` or `delete` declared again is named after the
+interface, `readComments`, not after the item: give it
+`@operationId("readComment")` to keep the item's name.

package/docs/roadmap.md

@@ -6,6 +6,28 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Now
 
+- **Resource ids in the singular.** `Resource` names `read`, `create`,
+  `update` and `delete` after its item, `readPost`, and `list` after the
+  interface, `listPosts`, instead of `readPosts`.
+
+## Later
+
+- **`ETag` and conditional requests.** `ETag`, with `If-None-Match` and
+  `If-Match`, once the `@nxgt/*` packages send one the same way. The
+  optimistic lock is the body's `version` today (`Versioned`).
+
+## Shipped
+
+### 0.2.0
+
+- **One reply per status.** An operation that declares a reply without a
+  body beside one with a body, such as `AuthenticationRequired` and
+  `Unauthorized`, is an error, `duplicate-status-reply`, and two replies with
+  a body of one status code a warning, `merged-status-reply`, instead of
+  replies the emitter merges without a word.
+
+### 0.1.0
+
 - **Error replies.** The envelope `@nxgt/openapi-hono` sends, and the
   400, 401, 403, 404, 409, 422, 429 and 500 responses, with any other status
   through `ErrorResponse<Status>`.
@@ -24,15 +46,3 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
   by `orderBy` and `direction`.
 - **Operation ids.** `@operationIds` names an interface's operations
   `listPosts`, `createPosts`, instead of `Posts_list`.
-
-## Next
-
-- **One reply per status.** An error when an operation declares two replies
-  of one status, such as `AuthenticationRequired` and `Unauthorized`, which
-  the emitter merges without a warning today.
-
-## Later
-
-- **`ETag` and conditional requests.** `ETag`, with `If-None-Match` and
-  `If-Match`, once the `@nxgt/*` packages send one the same way. The
-  optimistic lock is the body's `version` today (`Versioned`).

package/docs/troubleshooting.md

@@ -60,17 +60,22 @@ operation:
   `extends` copies it as is;
 - an `@operationId` written elsewhere takes the id `@operationIds` gives;
 - an operation declared in the service namespace is named after itself:
-  `op listPets()` takes the id of `Pets.list`.
+  `op listPets()` takes the id of `Pets.list`;
+- two interfaces extend `Resource` with one item: `Authors` and
+  `ArchivedAuthors` both give `readAuthor`, as `Resource` names `read`,
+  `create`, `update` and `delete` after the item.
 
 ```text
 error @nxgt/typespec/duplicate-operation-id: Two operations are named listPets: an OpenAPI operation id must be unique.
 ```
 
-**Why:** `@operationIds` names each operation `<operation><Interface>`, without
-the namespace. `@typespec/openapi3` would emit both ids without a word, and
+**Why:** `@operationIds` names each operation `<operation><Interface>`
+(`<operation><Item>` for `Resource`'s `read`, `create`, `update` and
+`delete`), without the namespace. `@typespec/openapi3` would emit both ids without a word, and
 the generator would then refuse the spec.
 
-**Fix:** give one of them its own `@operationId`. An inherited operation takes
+**Fix:** give one of them its own `@operationId`, for a `Resource` in the
+interface that extends it ([Resources](guide/resources.md#two-resources-of-one-item)). An inherited operation takes
 one by being declared again in the interface that extends:
 
 ```tsp
@@ -84,6 +89,61 @@ interface Drafts extends Posts {
 }
 ```
 
+## `declares a reply without a body and one with a body of status …`
+
+**When:** an operation declares, for one status, a reply without a body and
+one with a body, such as the guard's 401 and the handler's:
+
+```tsp
+@get list(): Post[] | AuthenticationRequired | Unauthorized;
+```
+
+```text
+error @nxgt/typespec/duplicate-status-reply: list declares a reply without a body and one with a body of status 401: the emitter merges them into one, and the reply without a body is lost. Declare the one the route sends.
+```
+
+**Why:** OpenAPI has one reply per status. `@typespec/openapi3` merges the two
+without a warning: the 401 keeps the envelope, and a client never learns the
+guard's reply has no body.
+
+**Fix:** declare the one the route sends. A route behind a
+`@nxgt/janus-hono` guard sends `AuthenticationRequired`; a handler that
+answers with the envelope, `Unauthorized`:
+
+```tsp
+@get list(): Post[] | AuthenticationRequired;
+```
+
+## `declares two replies with a body of status …`
+
+**When:** a warning: an operation declares two replies with a body for one
+status code, such as the idempotent write's 409 beside the optimistic
+lock's, or its 422, `IdempotencyKeyReused`, beside `UnprocessableEntity`:
+
+```tsp
+@post create(@body post: Post): Post | IdempotencyInProgress | Conflict;
+```
+
+```text
+warning @nxgt/typespec/merged-status-reply: create declares two replies with a body of status 409: the emitter merges their bodies under the first one's description. Declare the one the route sends.
+```
+
+**Why:** `@typespec/openapi3` keeps both bodies, as one reply whose body is
+either, under the first one's description: the second's is gone, and a
+header either reply declares required becomes optional.
+
+**Fix:** declare the one the route sends. Both carry the envelope, and the
+`message` key tells them apart:
+
+```tsp
+@post create(@body post: Post): Post | IdempotencyInProgress;
+```
+
+Two plain bodies, `Post | Draft`, are one reply whose body is either; two
+`@error` models without a `@statusCode` share `default`, and one
+description; bodies of different content types are negotiated. All three
+pass.
+
 ## `Unknown decorator @operationId`
 
 **When:** a spec writes `@operationId` next to `@operationIds`.

package/lib/operation-ids.tsp

@@ -20,3 +20,11 @@ namespace Nxgt;
  * ```
  */
 extern dec operationIds(target: Interface);
+
+namespace Private {
+  /**
+   * Names the operation after `item`, `<operation><Item>`, where
+   * `@operationIds` names it. `Resource`'s alone: not public.
+   */
+  extern dec itemOperation(target: Operation, item: Model);
+}

package/lib/resources.tsp

@@ -23,8 +23,9 @@ model SortParameters<Field extends string> {
  * The five operations of a resource, at `/<route>` and `/<route>/{id}`:
  * `list` pages by offset, with the `Filters` the spec writes and a sort by
  * `SortField`; `read`, `create`, `update` (a merge patch) and `delete`.
- * Extend it with `@route`; `@operationIds` names the operations after the
- * interface that extends it: `listPosts`, `readPosts`…
+ * Extend it with `@route`; `@operationIds` names `list` after the interface
+ * that extends it, and the others after `Item`: `listPosts`, `readPost`,
+ * `createPost`, `updatePost`, `deletePost`.
  *
  * @template Item The resource's model.
  * @template Filters A model of `@query` properties, spread into `list`.
@@ -43,10 +44,12 @@ interface Resource<
   list(...Filters, ...PageParameters, ...SortParameters<SortField>): Page<Item>;
 
   /** One resource. */
+  @Private.itemOperation(Item)
   @get
   read(@path id: Id): Item | NotFound;
 
   /** Creates a resource. */
+  @Private.itemOperation(Item)
   @post
   create(@body item: Create<Item>): {
     @statusCode _: 201;
@@ -54,10 +57,12 @@ interface Resource<
   } | BadRequest | Conflict;
 
   /** Updates a resource with a merge patch. */
+  @Private.itemOperation(Item)
   @patch
   update(@path id: Id, @body item: MergePatchUpdate<Item>): Item | BadRequest | NotFound | Conflict;
 
   /** Deletes a resource. */
+  @Private.itemOperation(Item)
   @delete
   delete(@path id: Id): NoContentResponse | NotFound;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",