bazis 0.98.5 → 0.98.7

package/core/http/HttpServer.ts

@@ -6,7 +6,8 @@ import { HttpContext } from "./HttpContext/HttpContext";
 import { holdResponseScope } from "./HttpContext/responseLifetime";
 import { inspectableRedirectResponse } from "./HttpContext/inspectableRedirects";
 import { accessLog } from "./Middleware/accessLog";
-import { cors, isPreflight, preflightResponse } from "./Middleware/cors";
+import { cors, corsOptionsOf, isPreflight, preflightResponse, type CorsOptions } from "./Middleware/cors";
+import { isCorrelationIdMiddleware } from "./correlation/createCorrelationIdMiddleware";
 import { errorHandler } from "./Middleware/errorHandler";
 import { runPipeline } from "./Middleware/pipeline";
 import { applySecurityHeaders, securityHeaders } from "./Middleware/securityHeaders";
@@ -75,6 +76,8 @@ export class HttpServer implements HostedService {
   private server?: ReturnType<typeof Bun.serve>;
   private router?: Router;
   private readVersion: VersionReader = () => undefined;
+  /** CORS options for every preflight: `cors` or a `cors()` among the global middleware. */
+  private globalCors: CorsOptions | undefined;
   /** Body cap in bytes; `undefined` when the limit is disabled (`maxBodyBytes: 0`). */
   private readonly maxBodyBytes?: number;
   private readonly requestScopeDisposeTimeoutMs?: number;
@@ -161,8 +164,13 @@ export class HttpServer implements HostedService {
         onUnexpectedError: this.collectErrorHook(),
       }),
     );
-    this.shortCircuitChain = [...serverChain];
-    serverChain.push(...this.collectServerMiddleware());
+    const serverMiddleware = this.collectServerMiddleware();
+    // Responses produced before routing (404, 405, 413, preflight, docs,
+    // health) still carry the correlation id of a global correlation middleware.
+    this.shortCircuitChain = [...serverChain, ...serverMiddleware.filter(isCorrelationIdMiddleware)];
+    // A global `cors()` among the middleware answers preflights like `cors`.
+    this.globalCors = this.options.cors || serverMiddleware.map(corsOptionsOf).find((options) => options !== undefined);
+    serverChain.push(...serverMiddleware);
 
     const builder = new RouterBuilder(
       serverChain,
@@ -367,9 +375,11 @@ export class HttpServer implements HostedService {
       }
     }
 
-    if (this.options.cors && isPreflight(request)) {
-      const corsOptions = this.options.cors;
-      return this.runShortCircuit(request, url, clientIp, () => preflightResponse(corsOptions, request));
+    if (isPreflight(request)) {
+      const corsOptions = this.globalCors ?? this.routeCors(request, url);
+      if (corsOptions !== undefined) {
+        return this.runShortCircuit(request, url, clientIp, () => preflightResponse(corsOptions, request));
+      }
     }
 
     const segments = parseRequestPath(url.pathname);
@@ -430,6 +440,15 @@ export class HttpServer implements HostedService {
     }
   }
 
+  /** CORS options of the route a preflight asks about (its `Access-Control-Request-Method`). */
+  private routeCors(request: Request, url: URL): CorsOptions | undefined {
+    const segments = parseRequestPath(url.pathname);
+    const method = request.headers.get("access-control-request-method")?.trim().toUpperCase();
+    if (!segments || !method) return undefined;
+    const match = this.router!.match(method, segments, this.readVersion(request, url));
+    return match.kind === "matched" ? match.action.cors : undefined;
+  }
+
   private async runShortCircuit(
     request: Request,
     url: URL,

package/core/http/Middleware/accessLog.ts

@@ -7,7 +7,7 @@ export interface AccessLogEntry {
   readonly method: string;
   readonly path: string;
   readonly status: number;
-  /** Wall-clock time spent in the pipeline, in milliseconds. */
+  /** Wall-clock time spent in the pipeline, in milliseconds, rounded to 0.01. */
   readonly durationMs: number;
   /** Correlation id from {@link createCorrelationIdMiddleware}, if present. */
   readonly requestId?: string;
@@ -73,7 +73,7 @@ export function accessLog(options: AccessLogOptions = {}): HttpMiddleware {
             method: ctx.method,
             path: ctx.path,
             status: ctx.response?.status ?? 0,
-            durationMs: performance.now() - startedAt,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
             ...(typeof requestId === "string" ? { requestId } : {}),
           });
         }

package/core/http/Middleware/cors.ts

@@ -22,6 +22,14 @@ export interface CorsOptions {
 
 const DEFAULT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"] as const;
 
+/** Options of a middleware created by {@link cors}; the server answers preflights with them. */
+const CORS_OPTIONS = Symbol("bazis:http:cors-options");
+
+/** Options of a {@link cors} middleware, or undefined for any other middleware. */
+export function corsOptionsOf(middleware: HttpMiddleware): CorsOptions | undefined {
+  return (middleware as HttpMiddleware & { [CORS_OPTIONS]?: CorsOptions })[CORS_OPTIONS];
+}
+
 function assertSafeCorsOptions(options: CorsOptions): void {
   if (!options.credentials) {
     return;
@@ -119,12 +127,14 @@ export function preflightResponse(options: CorsOptions, request: Request): Respo
 
 /**
  * CORS middleware: adds response headers for cross-origin requests.
- * Use globally via `httpModule({ cors })` (which also answers preflights)
- * or per controller/route via `@Middleware(cors({...}))`.
+ * Use globally via `httpModule({ cors })` or per controller/route via
+ * `@Middleware(cors({...}))`. Either way the server answers preflights
+ * (`OPTIONS` with `Access-Control-Request-Method`) with these options: a
+ * route's own `cors()` applies to preflights of that route.
  */
 export function cors(options: CorsOptions = {}): HttpMiddleware {
   assertSafeCorsOptions(options);
-  return async (ctx, next) => {
+  const middleware: HttpMiddleware = async (ctx, next) => {
     await next();
     const requestOrigin = ctx.header("origin");
     if (!ctx.response) {
@@ -157,4 +167,6 @@ export function cors(options: CorsOptions = {}): HttpMiddleware {
       }
     }
   };
+  Object.defineProperty(middleware, CORS_OPTIONS, { value: options });
+  return middleware;
 }

package/core/http/OpenApi/openApiDocument.ts

@@ -25,12 +25,28 @@ export interface HttpOpenApiDocumentBuildInput {
   readonly version: string;
 }
 
+/** Body of every error response: `{ "error": "...", "details": ... }` (see Middleware/errorHandler). */
+const ERROR_SCHEMA_NAME = "HttpErrorResponse";
+const ERROR_SCHEMA: OpenApiSchema = {
+  type: "object",
+  description: "Error response of the bazis HTTP server.",
+  properties: {
+    error: { type: "string", description: "Human-readable error message." },
+    details: { description: "Error details, for example the list of validation errors." },
+  },
+  required: ["error"],
+};
+const ERROR_DESCRIPTIONS: Readonly<Record<number, string>> = {
+  400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found", 409: "Conflict",
+  413: "Payload Too Large", 415: "Unsupported Media Type", 429: "Too Many Requests",
+};
+
 export function buildHttpOpenApiDocument(input: HttpOpenApiDocumentBuildInput): OpenApiSchema {
   const generated = getGeneratedOpenApiMetadata(input.controllers);
   const documentInput: LibraryOpenApiDocumentBuildInput = {
     title: input.title,
     version: input.version,
-    schemas: generated.schemas,
+    schemas: { [ERROR_SCHEMA_NAME]: ERROR_SCHEMA, ...generated.schemas },
     operations: collectOpenApiOperations(input, generated),
     generatedBy: "bazis:di-generate",
   };
@@ -89,16 +105,18 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
   const version = input.action.version ?? input.meta.version;
   const auth = resolveAuthorizeMeta(input.controllerClass, input.methodName);
   const generatedOperation = input.generated.operations[input.controllerClass.name]?.[methodName];
-  const status = String(successStatus(input.httpMethod, input.action));
+  const status = String(successStatus(input.httpMethod, input.action, generatedOperation?.status));
   const responseSchema = generatedOperation?.response;
   const contentType = input.action.produces ?? "application/json";
+  const authorized = !auth.allowAnonymous && auth.authorize !== undefined;
 
   return {
     path: input.path,
     httpMethod: input.httpMethod,
     tag: tagName(input.meta, input.controllerClass),
     operationId: stableHttpOperationId(input.httpMethod, input.path),
-    summary: `${normalizedMethod(input.httpMethod)} ${input.path}`,
+    summary: generatedOperation?.summary ?? `${normalizedMethod(input.httpMethod)} ${input.path}`,
+    ...(generatedOperation?.description !== undefined ? { description: generatedOperation.description } : {}),
     parameters: collectParameters(
       input.bindings,
       input.versioning,
@@ -117,8 +135,9 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
             },
           }
         : { description: "Success" },
+      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors)),
     },
-    authorized: !auth.allowAnonymous && auth.authorize !== undefined,
+    authorized,
     ...(version !== undefined ? { versions: [version] } : {}),
   };
 }
@@ -305,11 +324,42 @@ function schemaForConstraint(constraint: string | undefined): OpenApiSchema {
   }
 }
 
-function successStatus(method: string, action: ActionMeta): number {
-  if (action.httpCode !== undefined) {
-    return action.httpCode;
+function successStatus(method: string, action: ActionMeta, generated: number | undefined): number {
+  return action.httpCode ?? generated ?? (method === "DELETE" ? 204 : 200);
+}
+
+/**
+ * Errors the operation can answer with: 400 when the request carries values
+ * that are converted or validated (body, list query, query, typed route
+ * parameters), 401/403 under @Authorize, and the errors the method body
+ * returns or throws itself.
+ */
+function errorStatuses(
+  bindings: readonly ParameterBinding[],
+  authorized: boolean,
+  generated: readonly number[] | undefined,
+): number[] {
+  const statuses = new Set(generated ?? []);
+  const validated = bindings.some((binding) =>
+    binding.source === "body" || binding.source === "list" || binding.source === "query"
+    || (binding.source === "route" && binding.type !== undefined && binding.type !== "string"));
+  if (validated) statuses.add(400);
+  if (authorized) {
+    statuses.add(401);
+    statuses.add(403);
+  }
+  return [...statuses].sort((a, b) => a - b);
+}
+
+function errorResponses(statuses: readonly number[]): Record<string, OpenApiSchema> {
+  const responses: Record<string, OpenApiSchema> = {};
+  for (const status of statuses) {
+    responses[String(status)] = {
+      description: ERROR_DESCRIPTIONS[status] ?? "Error",
+      content: { "application/json": { schema: { $ref: `#/components/schemas/${ERROR_SCHEMA_NAME}` } } },
+    };
   }
-  return method === "DELETE" ? 204 : 200;
+  return responses;
 }
 
 function tagName(meta: ControllerMeta, controllerClass: Class<object>): string {

package/core/http/Routing/Router.ts

@@ -1,4 +1,5 @@
 import type { HttpMiddleware } from "../Middleware/types";
+import type { CorsOptions } from "../Middleware/cors";
 import { HttpSetupError } from "../Errors/HttpError";
 import { INVALID } from "../Binding/convert";
 import type { SegmentConstraint, TemplateSegment } from "./template";
@@ -13,6 +14,8 @@ export interface RouteAction {
   readonly name: string;
   /** Action-specific body cap in bytes; undefined inherits the server cap. */
   readonly maxBodyBytes?: number;
+  /** Options of the action's or controller's `cors()` middleware, for preflights. */
+  readonly cors?: CorsOptions;
 }
 
 interface RouteEntry {

package/core/http/Routing/RouterBuilder.ts

@@ -6,6 +6,7 @@ import { controllerMetaOf, type ActionMeta, type ControllerMeta } from "../Decor
 import { HttpSetupError } from "../Errors/HttpError";
 import type { HttpContext } from "../HttpContext/HttpContext";
 import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+import { corsOptionsOf } from "../Middleware/cors";
 import { normalizeResult } from "../Results/normalize";
 import type { ApiVersioningOptions, RouteMiddlewareComposer } from "../options";
 import { createAuthorizeComposer } from "../Authorization/authorizeComposer";
@@ -84,6 +85,7 @@ export class RouterBuilder {
         version,
         name: `${controllerClass.name}.${String(methodName)}`,
         maxBodyBytes: action.maxBodyBytes,
+        cors: routeCors(meta, action),
       };
       for (const declaration of action.routes) {
         const versionSegment = useUrlVersioning && version !== undefined ? `v${version}` : undefined;
@@ -192,6 +194,19 @@ export class RouterBuilder {
  * but has no bindings was most likely added or changed after the last codegen:
  * its arguments would silently get wrong values, so the server refuses to start.
  */
+/** The action's own `cors()` wins over the controller's. */
+function routeCors(meta: ControllerMeta, action: ActionMeta): ReturnType<typeof corsOptionsOf> {
+  for (const middleware of [...action.middleware].reverse()) {
+    const options = corsOptionsOf(middleware);
+    if (options !== undefined) return options;
+  }
+  for (const middleware of [...meta.middleware].reverse()) {
+    const options = corsOptionsOf(middleware);
+    if (options !== undefined) return options;
+  }
+  return undefined;
+}
+
 function assertBindingsFresh(
   controllerClass: Class<object>,
   methodName: string | symbol,

package/core/http/correlation/createCorrelationIdMiddleware.ts

@@ -14,6 +14,14 @@ export interface CorrelationIdMiddlewareOptions {
   readonly validateIncomingId?: (value: string) => boolean;
 }
 
+/** Marks the middleware so the server also applies it to responses produced before routing. */
+const CORRELATION_ID_MIDDLEWARE = Symbol("bazis:http:correlation-id");
+
+/** True for a middleware created by {@link createCorrelationIdMiddleware}. */
+export function isCorrelationIdMiddleware(middleware: HttpMiddleware): boolean {
+  return (middleware as HttpMiddleware & { [CORRELATION_ID_MIDDLEWARE]?: true })[CORRELATION_ID_MIDDLEWARE] === true;
+}
+
 const DEFAULT_REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/+\-=]{0,127}$/;
 const TRACEPARENT = /^[\da-f]{2}-([\da-f]{32})-([\da-f]{16})-[\da-f]{2}(?:-[\x21-\x7e]+)?$/i;
 
@@ -21,6 +29,8 @@ const TRACEPARENT = /^[\da-f]{2}-([\da-f]{32})-([\da-f]{16})-[\da-f]{2}(?:-[\x21
  * Ensures one correlation ID per HTTP request: reads `x-request-id` or
  * generates a UUID, stores it on {@link HttpContext.state}, echoes it on the
  * response, and binds it to async local storage for application logs.
+ * Registered among the server's global middleware, it also applies to the
+ * responses the server produces before routing (404, 405, 413, preflight).
  */
 export function createCorrelationIdMiddleware(
   options: CorrelationIdMiddlewareOptions = {},
@@ -29,7 +39,7 @@ export function createCorrelationIdMiddleware(
   const generateId = options.generateId ?? (() => crypto.randomUUID());
   const validateIncomingId = options.validateIncomingId ?? ((value: string) => DEFAULT_REQUEST_ID.test(value));
 
-  return async (ctx, next) => {
+  const middleware: HttpMiddleware = async (ctx, next) => {
     const incoming = ctx.header(headerName);
     const trimmedIncoming = incoming?.trim();
     const generated = (): string => {
@@ -64,6 +74,8 @@ export function createCorrelationIdMiddleware(
       });
     }
   };
+  Object.defineProperty(middleware, CORRELATION_ID_MIDDLEWARE, { value: true });
+  return middleware;
 }
 
 function normalizeTraceparent(value: string | undefined): string | undefined {

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.5" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.7" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/scripts/di-generate.ts

@@ -1360,8 +1360,7 @@ function collectOpenApiOperation(controllerName: string, method: ts.MethodDeclar
   if (!ts.isIdentifier(method.name)) {
     return;
   }
-  const response = openApiCodegen.responseSchemaFromMethod(method);
-  (openApiOperations[controllerName] ??= {})[method.name.text] = response === undefined ? {} : { response };
+  (openApiOperations[controllerName] ??= {})[method.name.text] = openApiCodegen.operationFromMethod(method);
 }
 
 /** True if the class has an `extends ListRequest` (with or without type args). */

package/library/openapi/codegen.ts

@@ -5,6 +5,14 @@ export type OpenApiCodegenSchema = Record<string, unknown>;
 
 export interface OpenApiCodegenOperationSpec {
   readonly response?: OpenApiCodegenSchema;
+  /** Success status when every success return uses the same result helper (`Created` -> 201). */
+  readonly status?: number;
+  /** Error statuses returned (`NotFound(...)`) or thrown (`throw new NotFoundError()`) in the method body. */
+  readonly errors?: readonly number[];
+  /** First line of the method's JSDoc. */
+  readonly summary?: string;
+  /** The rest of the method's JSDoc. */
+  readonly description?: string;
 }
 
 export interface OpenApiCodegenAnalyzer {
@@ -15,6 +23,8 @@ export interface OpenApiCodegenAnalyzer {
   schemaFromDeclaration(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration): OpenApiCodegenSchema;
   schemaNameForDeclaration(name: string, declaration: ts.Declaration | undefined): string;
   responseSchemaFromMethod(method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined;
+  /** Response schema, statuses and JSDoc of a controller method. */
+  operationFromMethod(method: ts.MethodDeclaration): OpenApiCodegenOperationSpec;
 }
 
 export interface OpenApiCodegenAnalyzerInput {
@@ -32,6 +42,14 @@ const SUCCESS_RESULT_HELPERS = new Set(["Ok", "Accepted"]);
 const CREATED_RESULT_HELPERS = new Set(["Created"]);
 const EMPTY_SUCCESS_RESULT_HELPERS = new Set(["NoContent", "Redirect", "File"]);
 const ERROR_RESULT_HELPERS = new Set(["BadRequest", "Unauthorized", "Forbidden", "NotFound", "Conflict", "InternalServerError"]);
+const SUCCESS_HELPER_STATUS: Readonly<Record<string, number>> = { Ok: 200, Accepted: 202, Created: 201, NoContent: 204 };
+const ERROR_HELPER_STATUS: Readonly<Record<string, number>> = {
+  BadRequest: 400, Unauthorized: 401, Forbidden: 403, NotFound: 404, Conflict: 409,
+};
+const ERROR_CLASS_STATUS: Readonly<Record<string, number>> = {
+  BadRequestError: 400, UnauthorizedError: 401, ForbiddenError: 403, NotFoundError: 404,
+  PayloadTooLargeError: 413, UnsupportedMediaTypeError: 415, TooManyRequestsError: 429,
+};
 const OPENAPI_EMPTY_TYPE_NAMES = new Set(["HttpResult", "Response", "Blob", "ReadableStream", "Uint8Array"]);
 const OPENAPI_BUILTIN_TYPE_NAMES = new Set([
   "Array",
@@ -77,7 +95,8 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
       const baseSchema = typeNode ? schemaFromTypeNode(typeNode) : schemaFromInitializer(schemaInitializer(member));
       const validators = validatorOptionsOf(member);
       const schema = validators.reduce((current, options) => applyValidatorOptions(current, options), baseSchema);
-      properties[name] = schema;
+      const description = documentationOf(member.name);
+      properties[name] = description === undefined ? schema : { ...schema, description };
       if (isRequiredProperty(member, ownerKind, validators)) {
         required.push(name);
       }
@@ -89,12 +108,95 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
     return schema;
   };
 
-  const responseSchemaFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined => {
-    const inferred = responseSchemaFromReturnExpressions(method);
-    if (inferred !== undefined) {
-      return inferred;
+  /** JSDoc text of a declaration name, without tags; undefined when there is none. */
+  const documentationOf = (name: ts.Node): string | undefined => {
+    const symbol = checker.getSymbolAtLocation(name);
+    const text = symbol === undefined ? "" : ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim();
+    return text.length > 0 ? text : undefined;
+  };
+
+  const operationFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenOperationSpec => {
+    const response = responseSchemaFromMethod(method);
+    const { status, errors } = statusesFromMethod(method);
+    const documentation = documentationOf(method.name);
+    const [summary, ...rest] = documentation?.split(/\r?\n/) ?? [];
+    const description = rest.join("\n").trim();
+    return {
+      ...(response !== undefined ? { response } : {}),
+      ...(status !== undefined ? { status } : {}),
+      ...(errors.length > 0 ? { errors } : {}),
+      ...(summary !== undefined && summary.trim().length > 0 ? { summary: summary.trim() } : {}),
+      ...(description.length > 0 ? { description } : {}),
+    };
+  };
+
+  /**
+   * Success and error statuses visible in the method body: result helpers in
+   * `return` statements and `throw new <HttpError subclass>`. Errors thrown
+   * by called services are not visible here.
+   */
+  const statusesFromMethod = (method: ts.MethodDeclaration): { status?: number; errors: number[] } => {
+    const success = new Set<number>();
+    const errors = new Set<number>();
+    const addReturn = (expression: ts.Expression): void => {
+      const unwrapped = unwrapExpression(expression);
+      if (ts.isConditionalExpression(unwrapped)) {
+        addReturn(unwrapped.whenTrue);
+        addReturn(unwrapped.whenFalse);
+        return;
+      }
+      const name = ts.isCallExpression(unwrapped) ? callExpressionName(unwrapped) : undefined;
+      if (name !== undefined && SUCCESS_HELPER_STATUS[name] !== undefined) {
+        success.add(SUCCESS_HELPER_STATUS[name]);
+      } else if (name !== undefined && ERROR_HELPER_STATUS[name] !== undefined) {
+        errors.add(ERROR_HELPER_STATUS[name]);
+      } else if (name === "StatusCode" && ts.isCallExpression(unwrapped)) {
+        const status = numericLiteralValue(unwrapped.arguments[0]);
+        if (status === undefined) success.add(-1);
+        else if (status >= 400 && status < 500) errors.add(status);
+        else if (status >= 200 && status < 300) success.add(status);
+      } else if (name === undefined || !EMPTY_SUCCESS_RESULT_HELPERS.has(name) && !ERROR_RESULT_HELPERS.has(name)) {
+        success.add(200);
+      } else {
+        success.add(-1);
+      }
+    };
+    const visit = (node: ts.Node): void => {
+      if (node !== method.body && isNestedFunctionLike(node)) return;
+      if (ts.isReturnStatement(node)) {
+        if (node.expression !== undefined) addReturn(node.expression);
+        return;
+      }
+      if (ts.isThrowStatement(node) && ts.isNewExpression(unwrapExpression(node.expression))) {
+        const status = httpErrorStatus(checker.getTypeAtLocation(node.expression));
+        if (status !== undefined) errors.add(status);
+      }
+      ts.forEachChild(node, visit);
+    };
+    if (method.body !== undefined) ts.forEachChild(method.body, visit);
+    const [only] = success;
+    return {
+      ...(success.size === 1 && only !== undefined && only !== 200 && only !== -1 ? { status: only } : {}),
+      errors: [...errors].sort((a, b) => a - b),
+    };
+  };
+
+  /** Status of an HttpError subclass by its class chain (`class TaskNotFound extends NotFoundError`). */
+  const httpErrorStatus = (type: ts.Type): number | undefined => {
+    let current: ts.Type | undefined = type;
+    for (let depth = 0; current !== undefined && depth < 16; depth += 1) {
+      const name = current.getSymbol()?.getName();
+      if (name !== undefined && ERROR_CLASS_STATUS[name] !== undefined) return ERROR_CLASS_STATUS[name];
+      current = current.isClass() ? checker.getBaseTypes(current)[0] : undefined;
     }
-    return method.type ? responseSchemaFromType(method.type) : undefined;
+    return undefined;
+  };
+
+  const responseSchemaFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined => {
+    // A declared return type is the contract; result-helper types
+    // (HttpResult, Response) carry no schema and fall back to the returns.
+    const declared = method.type ? responseSchemaFromType(method.type) : undefined;
+    return declared ?? responseSchemaFromReturnExpressions(method);
   };
 
   const schemaFromTypeNode = (node: ts.TypeNode): OpenApiCodegenSchema => {
@@ -418,21 +520,28 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
   return {
     schemaFromMembers,
     schemaFromDeclaration(declaration) {
-      if (!declaration.heritageClauses?.some(clause => clause.token === ts.SyntaxKind.ExtendsKeyword)) {
-        return schemaFromMembers(declaration.members, ts.isClassDeclaration(declaration) ? "class" : "interface");
-      }
-      // Effective instance properties include imported and indirect base classes.
-      // Keep original property declarations so their Validator rules remain visible.
-      const properties = checker.getPropertiesOfType(checker.getTypeAtLocation(declaration));
-      const members = properties.flatMap(property => {
-        const member = property.valueDeclaration ?? property.declarations?.[0];
-        return member !== undefined && (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) ? [member] : [];
-      });
-      return schemaFromMembers(members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+      const schema = schemaFromDeclarationMembers(declaration);
+      const description = declaration.name === undefined ? undefined : documentationOf(declaration.name);
+      return description === undefined ? schema : { description, ...schema };
     },
     schemaNameForDeclaration,
     responseSchemaFromMethod,
+    operationFromMethod,
   };
+
+  function schemaFromDeclarationMembers(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration): OpenApiCodegenSchema {
+    if (!declaration.heritageClauses?.some(clause => clause.token === ts.SyntaxKind.ExtendsKeyword)) {
+      return schemaFromMembers(declaration.members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+    }
+    // Effective instance properties include imported and indirect base classes.
+    // Keep original property declarations so their Validator rules remain visible.
+    const properties = checker.getPropertiesOfType(checker.getTypeAtLocation(declaration));
+    const members = properties.flatMap(property => {
+      const member = property.valueDeclaration ?? property.declarations?.[0];
+      return member !== undefined && (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) ? [member] : [];
+    });
+    return schemaFromMembers(members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+  }
 }
 
 function collectSchemaNameIndex(sourceFiles: readonly ts.SourceFile[]): Map<string, Set<string>> {

package/library/openapi/document.ts

@@ -4,6 +4,7 @@ type OpenApiOperation = {
   tags: string[];
   operationId: string;
   summary: string;
+  description?: string;
   parameters?: OpenApiParameter[];
   requestBody?: OpenApiSchema;
   responses: Record<string, OpenApiSchema>;
@@ -152,6 +153,9 @@ function operationFromCatalog(item: OpenApiCatalogOperation): OpenApiOperation {
     summary: item.summary ?? `${normalizedMethod(item.httpMethod)} ${item.path}`,
     responses: { ...item.responses },
   };
+  if (item.description !== undefined) {
+    operation.description = item.description;
+  }
   const parameters = mergeParameters(item.parameters ?? []);
   if (parameters.length > 0) {
     operation.parameters = parameters;

package/library/openapi/types.ts

@@ -2,6 +2,14 @@ export type OpenApiSchema = Readonly<Record<string, unknown>>;
 
 export interface GeneratedOpenApiOperationMetadata {
   readonly response?: OpenApiSchema;
+  /** Success status from the method's result helpers (`Created` -> 201). */
+  readonly status?: number;
+  /** Error statuses returned or thrown in the method body. */
+  readonly errors?: readonly number[];
+  /** First line of the method's JSDoc. */
+  readonly summary?: string;
+  /** The rest of the method's JSDoc. */
+  readonly description?: string;
 }
 
 export interface GeneratedOpenApiMetadata {
@@ -53,6 +61,7 @@ export interface OpenApiCatalogOperation {
   readonly tag: string;
   readonly operationId: string;
   readonly summary?: string;
+  readonly description?: string;
   readonly parameters?: readonly OpenApiParameter[];
   readonly requestBody?: OpenApiSchema;
   readonly responses: Readonly<Record<string, OpenApiSchema>>;

package/library/openapi/ui.ts

@@ -148,7 +148,7 @@ export function renderOpenApiHtml(title: string, specPath: string): string {
       method.textContent = row.method;
       const summary = document.createElement("span");
       summary.className = "summary";
-      summary.textContent = row.operation.operationId || row.operation.summary || "";
+      summary.textContent = row.operation.summary || row.operation.operationId || "";
       line.append(method, summary);
       node.appendChild(line);
       const meta = document.createElement("div");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.5",
+  "version": "0.98.7",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",