@autoview/cli 0.1.0

package/src/utils/toEndpoints.test.ts

@@ -0,0 +1,251 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { toEndpoints, unsupportedOperations } from "./toEndpoints";
+
+// Build a normalized OpenApi.IDocument from a raw paths/schemas fragment, the
+// same way fromSwagger does (upgradeDocument). Keeps the fixtures terse.
+function doc(
+  paths: Record<string, unknown>,
+  schemas: Record<string, unknown> = {},
+) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "t", version: "1.0.0" },
+    paths,
+    components: { schemas },
+    // biome-ignore lint: test fixture
+  } as never);
+}
+
+const okJson = (ref: string) => ({
+  200: {
+    description: "ok",
+    content: { "application/json": { schema: { $ref: ref } } },
+  },
+});
+
+describe("toEndpoints — swagger-native READ layer", () => {
+  it("preserves query-string endpoints (the bug swagger-native fixed)", () => {
+    const eps = toEndpoints(
+      doc(
+        {
+          "/items/search": {
+            get: {
+              operationId: "search",
+              parameters: [
+                { name: "q", in: "query", required: true, schema: { type: "string" } },
+                { name: "page", in: "query", schema: { type: "integer" } },
+              ],
+              responses: okJson("#/components/schemas/Item"),
+            },
+          },
+        },
+        { Item: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+      ),
+    );
+    const search = eps.find((e) => e.path === "/items/search");
+    expect(search).toBeDefined();
+    expect(search!.query).not.toBeNull();
+  });
+
+  it("builds the query as a resolvable inline object (not nestia's dead $ref)", () => {
+    // nestia points route.query.schema at a synthetic `*.GetQuery` $ref that
+    // exists in no components map — reconstruct it inline from the parameters so
+    // a list call can fill required defaults instead of sending `query: {}`.
+    const eps = toEndpoints(
+      doc(
+        {
+          "/pet/findByStatus": {
+            get: {
+              operationId: "findByStatus",
+              parameters: [
+                { name: "status", in: "query", required: true, schema: { type: "string", enum: ["available", "pending", "sold"] } },
+                { name: "limit", in: "query", schema: { type: "integer" } },
+              ],
+              responses: okJson("#/components/schemas/Pet"),
+            },
+          },
+        },
+        { Pet: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+      ),
+    );
+    const q = eps.find((e) => e.path === "/pet/findByStatus")!.query as {
+      type: string;
+      properties: Record<string, unknown>;
+      required: string[];
+    };
+    expect(q.type).toBe("object");
+    expect(Object.keys(q.properties).sort()).toEqual(["limit", "status"]);
+    expect(q.required).toEqual(["status"]); // required flag preserved
+  });
+
+  it("promotes inline request/response bodies into named component schemas", () => {
+    const d = doc({
+      "/items": {
+        post: {
+          operationId: "create",
+          requestBody: {
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: { name: { type: "string" } },
+                  required: ["name"],
+                },
+              },
+            },
+          },
+          responses: {
+            201: {
+              description: "created",
+              content: {
+                "application/json": {
+                  schema: { type: "object", properties: { id: { type: "string" } } },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+    const ep = toEndpoints(d).find((e) => e.path === "/items")!;
+    // Inline body is not dropped — it is promoted to a named component and the
+    // promoted name resolves inside the document's components.
+    expect(ep.requestBody).not.toBeNull();
+    expect((d.components?.schemas ?? {})[ep.requestBody!.typeName]).toBeDefined();
+    expect(ep.responseBody).not.toBeNull();
+    expect((d.components?.schemas ?? {})[ep.responseBody!.typeName]).toBeDefined();
+  });
+
+  it("picks a 202 success body, never the error `default` response", () => {
+    // nestia only recognizes 200/201 as success; with a 202-only operation it
+    // falls back to `default` (the error schema). The real success is the 202.
+    const d = doc(
+      {
+        "/zip_downloads": {
+          post: {
+            operationId: "create",
+            responses: {
+              202: { description: "accepted", content: { "application/json": { schema: { $ref: "#/components/schemas/ZipDownload" } } } },
+              400: { description: "bad", content: { "application/json": { schema: { $ref: "#/components/schemas/ClientError" } } } },
+              default: { description: "err", content: { "application/json": { schema: { $ref: "#/components/schemas/ClientError" } } } },
+            },
+          },
+        },
+      },
+      {
+        ZipDownload: { type: "object", properties: { id: { type: "string" }, download_url: { type: "string" } }, required: ["id"] },
+        ClientError: { type: "object", properties: { code: { type: "string" }, message: { type: "string" } } },
+      },
+    );
+    const ep = toEndpoints(d).find((e) => e.path === "/zip_downloads")!;
+    expect(ep.responseBody?.typeName).toBe("ZipDownload");
+  });
+
+  it("treats a 204 no-content response as a null body, not the error `default`", () => {
+    const d = doc(
+      {
+        "/files/{id}": {
+          delete: {
+            operationId: "erase",
+            parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+            responses: {
+              204: { description: "deleted" },
+              default: { description: "err", content: { "application/json": { schema: { $ref: "#/components/schemas/ClientError" } } } },
+            },
+          },
+        },
+      },
+      { ClientError: { type: "object", properties: { code: { type: "string" } } } },
+    );
+    const ep = toEndpoints(d).find((e) => e.path === "/files/{id}")!;
+    expect(ep.responseBody).toBeNull();
+    expect(ep.responseSchema).toBeNull();
+  });
+
+  it("surfaces operations dropped for unsupported content types instead of losing them", () => {
+    const d = doc({
+      "/files/{id}": {
+        post: {
+          operationId: "upload",
+          requestBody: {
+            content: {
+              "application/octet-stream": {
+                schema: { type: "string", format: "binary" },
+              },
+            },
+          },
+          parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+          responses: { 200: { description: "ok" } },
+        },
+      },
+    });
+    const eps = toEndpoints(d);
+    const dropped = unsupportedOperations(d);
+    // The octet-stream op cannot become a route, but it must NOT vanish silently.
+    expect(eps.find((e) => e.path === "/files/{id}")).toBeUndefined();
+    expect(dropped.some((u) => u.path === "/files/{id}")).toBe(true);
+  });
+
+  it("exposes a list endpoint with MORE THAN ONE object query param (the dropped-list bug)", () => {
+    // nestia's HttpMigration refuses a route whose query has >1 object-typed
+    // parameter ("query typed parameters must be only one object type"). Apideck's
+    // `GET /accounting/invoices` carries `filter`, `sort` AND `pass_through`
+    // objects — the very list screen that produces ids for navigation. It must be
+    // exposed, and its reconstructed query must keep EVERY param (objects + prims).
+    const d = doc(
+      {
+        "/accounting/invoices": {
+          get: {
+            operationId: "invoicesAll",
+            parameters: [
+              { name: "filter", in: "query", schema: { $ref: "#/components/schemas/InvoicesFilter" } },
+              { name: "sort", in: "query", schema: { $ref: "#/components/schemas/InvoicesSort" } },
+              { name: "pass_through", in: "query", schema: { type: "object", properties: { k: { type: "string" } } } },
+              { name: "limit", in: "query", schema: { type: "integer" } },
+            ],
+            responses: okJson("#/components/schemas/Invoice"),
+          },
+        },
+      },
+      {
+        Invoice: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        InvoicesFilter: { type: "object", properties: { number: { type: "string" } } },
+        InvoicesSort: { type: "object", properties: { by: { type: "string" } } },
+      },
+    );
+    const ep = toEndpoints(d).find((e) => e.path === "/accounting/invoices");
+    expect(ep).toBeDefined();
+    // No longer reported as an unexposed/dropped operation.
+    expect(unsupportedOperations(d).some((u) => u.path === "/accounting/invoices")).toBe(false);
+    // The full query is preserved — both object params AND the primitive.
+    const q = ep!.query as { type: string; properties: Record<string, unknown> };
+    expect(q).not.toBeNull();
+    expect(Object.keys(q.properties).sort()).toEqual(["filter", "limit", "pass_through", "sort"]);
+  });
+
+  it("captures accessor, method, and path for every supported operation", () => {
+    const eps = toEndpoints(
+      doc(
+        {
+          "/items": { get: { operationId: "list", responses: okJson("#/components/schemas/Item") } },
+          "/items/{id}": {
+            get: {
+              operationId: "get",
+              parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+              responses: okJson("#/components/schemas/Item"),
+            },
+          },
+        },
+        { Item: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+      ),
+    );
+    expect(eps).toHaveLength(2);
+    for (const ep of eps) {
+      expect(ep.method).toBeTruthy();
+      expect(ep.path).toBeTruthy();
+      expect(ep.accessor.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/utils/toEndpoints.ts

@@ -0,0 +1,343 @@
+import { OpenApi } from "@typia/interface";
+import { HttpMigration, OpenApiTypeChecker } from "@typia/utils";
+
+import { normalizeForNestia } from "./normalizeForNestia";
+
+/**
+ * Swagger-native endpoint model — Step toward "swagger만 읽고 정확하게".
+ *
+ * Built directly from nestia's `HttpMigration.application(doc).routes`, the
+ * single source of truth that already carries accessor + query + path params +
+ * body + response for EVERY operation. Replaces the former
+ * `invertOpenApiDocument`, whose `r.query === null` filter silently dropped
+ * every query-string endpoint (search / filter / pagination) — see the bug
+ * this migration fixes.
+ *
+ * Shape mirrors the former endpoint model so the orchestrators change minimally
+ * (`document.operations` → `toEndpoints(document)`), plus the one field the old
+ * model could not express: {@link IAutoViewEndpoint.query}.
+ *
+ * Schemas are typed as `OpenApi.IJsonSchema` purely for structural reuse
+ * — at runtime they ARE standard OpenAPI schemas (the old invert did the same
+ * `as any` cast), so the existing `describeEndpoint*` / `renderJsonSchema`
+ * helpers keep working unchanged.
+ */
+export interface IAutoViewEndpoint {
+  method: string;
+  path: string;
+
+  /** SDK function path nestia assigns, e.g. `["items","search","get"]`. */
+  accessor: string[];
+
+  /** Last accessor segment — the SDK function name. */
+  name: string;
+
+  /** Human description (summary + description merged). */
+  description: string;
+
+  /** Path parameters (primitive). */
+  parameters: IAutoViewEndpoint.IParameter[];
+
+  /**
+   * Query-string schema as a single object, or `null` when the endpoint has no
+   * query. THIS is what the old AutoBE model could not hold.
+   */
+  query: OpenApi.IJsonSchema | null;
+
+  /** Request body reference, or `null`. */
+  requestBody: IAutoViewEndpoint.IBody | null;
+
+  /** Response body reference, or `null`. */
+  responseBody: IAutoViewEndpoint.IBody | null;
+
+  /**
+   * The raw success response schema, captured even when {@link responseBody} is
+   * `null` because the response is an INLINE object (not a named `$ref`) — e.g.
+   * DigitalOcean's `{ databases: [...] }`. Lets the consumability analysis
+   * introspect inline collection responses without changing the frontend path
+   * (which keys off the named {@link responseBody.typeName}).
+   */
+  responseSchema: OpenApi.IJsonSchema | null;
+}
+export namespace IAutoViewEndpoint {
+  export interface IParameter {
+    name: string;
+    description: string;
+    schema: OpenApi.IJsonSchema;
+  }
+  export interface IBody {
+    description: string;
+    /**
+     * Component schema name. For an array response (`Pet[]`) this is the
+     * ELEMENT type (`Pet`) with {@link isArray} set — so a list screen knows
+     * its row type and can derive table columns deterministically.
+     */
+    typeName: string;
+    /** True when the payload is an array of `typeName` (list response). */
+    isArray: boolean;
+  }
+}
+
+/**
+ * Convert a standard OpenAPI document into AutoView's endpoint list — every
+ * operation, query endpoints included.
+ */
+/** A segment usable as a JS property in `api.functional.<seg>`. */
+const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * True when every accessor segment is a valid JS identifier, so the generator
+ * can emit `api.functional.<a>.<b>(…)`. Some real swaggers (Box) use `#`
+ * fragments in their paths (`/shared_items#folders`, `/schema#add`), which
+ * nestia turns into accessor segments containing `#` — unusable as a dotted
+ * property and a hard syntax error in the generated TSX. Such operations are
+ * dropped from {@link toEndpoints} and surfaced by {@link unsupportedOperations}.
+ */
+export function isRenderableAccessor(accessor: string[]): boolean {
+  return accessor.length > 0 && accessor.every((s) => JS_IDENT.test(s));
+}
+
+export function toEndpoints(document: OpenApi.IDocument): IAutoViewEndpoint[] {
+  const app = HttpMigration.application(normalizeForNestia(document));
+  return app.routes
+    .filter((r) => isRenderableAccessor(r.accessor))
+    .map((r): IAutoViewEndpoint => {
+    const body = resolveBody(r.body);
+    const successPart = pickSuccess(r);
+    const success = resolveBody(successPart);
+    // Read description and query from the UNTOUCHED original operation, not the
+    // relaxed one HttpMigration saw — the relaxed copy may have shed some object
+    // query params just to let the route compose (see normalizeForNestia).
+    const operation = originalOperation(document, r.method, r.path) ?? r.operation();
+    return {
+      method: r.method,
+      path: r.path,
+      accessor: r.accessor,
+      name: r.accessor.at(-1) ?? r.path,
+      description: writeDescription(operation) ?? "",
+      parameters: r.parameters.map((p) => ({
+        name: p.key,
+        description: p.parameter().description ?? "",
+        // biome-ignore lint: structurally an OpenAPI schema, reused as-is
+        schema: p.schema as unknown as OpenApi.IJsonSchema,
+      })),
+      query: buildQuerySchema(operation, document),
+      requestBody: body,
+      responseBody: success,
+      responseSchema: successPart
+        ? // biome-ignore lint: structurally an OpenAPI schema, reused as-is
+          (successPart.schema as unknown as OpenApi.IJsonSchema)
+        : null,
+    };
+  });
+}
+
+/** Look up the source operation in the original document by method + path. */
+function originalOperation(
+  document: OpenApi.IDocument,
+  method: string,
+  path: string,
+): OpenApi.IOperation | undefined {
+  const item = (document.paths ?? {})[path] as
+    | Record<string, OpenApi.IOperation>
+    | undefined;
+  return item?.[method];
+}
+
+/**
+ * Build the query-object schema from the raw operation's `in: query`
+ * parameters, as an INLINE object (`{ type, properties, required }`).
+ *
+ * nestia's `route.query.schema` is a `$ref` to a synthetic `*.GetQuery` type
+ * that is registered in NEITHER the original document NOR the migration's own
+ * document — a dead reference. Resolving it yields nothing, so a list call's
+ * defaults came out empty (`query: {}`) and the server 400'd on a required
+ * param (petstore's `status`). Reconstructing the schema from the source
+ * parameters keeps it inline and resolvable by every consumer, and preserves
+ * each param's `required` flag, `enum`, and `default`.
+ */
+function buildQuerySchema(
+  operation: OpenApi.IOperation | undefined,
+  document: OpenApi.IDocument,
+): OpenApi.IJsonSchema | null {
+  const raw = operation?.parameters ?? [];
+  const properties: Record<string, OpenApi.IJsonSchema> = {};
+  const required: string[] = [];
+  for (const entry of raw) {
+    const p = derefParameter(entry, document);
+    if (p === undefined || p.in !== "query") continue;
+    properties[p.name] = (p.schema as OpenApi.IJsonSchema | undefined) ?? {};
+    if (p.required === true) required.push(p.name);
+  }
+  if (Object.keys(properties).length === 0) return null;
+  // biome-ignore lint: structurally an OpenAPI object schema
+  return { type: "object", properties, required } as OpenApi.IJsonSchema;
+}
+
+interface IRawParameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  schema?: unknown;
+}
+
+/** Resolve a `$ref` parameter against `components.parameters`; pass others through. */
+function derefParameter(
+  entry: unknown,
+  document: OpenApi.IDocument,
+): IRawParameter | undefined {
+  if (entry !== null && typeof entry === "object" && "$ref" in entry) {
+    const ref = (entry as { $ref: unknown }).$ref;
+    if (typeof ref !== "string") return undefined;
+    const name = ref.split("/").pop();
+    const params = (document.components as { parameters?: Record<string, unknown> } | undefined)
+      ?.parameters;
+    const target = name !== undefined ? params?.[name] : undefined;
+    return target as IRawParameter | undefined;
+  }
+  return entry as IRawParameter | undefined;
+}
+
+/** 2xx status codes whose JSON body is the success payload, in preference order. */
+const SUCCESS_CODES = ["200", "201", "202", "203", "206"] as const;
+
+/**
+ * Pick the real success-response body for a route.
+ *
+ * nestia's `HttpMigration` only recognizes `200`/`201` as success; when an
+ * operation's only 2xx is `202 Accepted` (a body that exists — e.g. Box's
+ * `POST /zip_downloads` → `ZipDownload`) or `204 No Content`, it falls back to
+ * the `default` response, which is almost always the ERROR schema
+ * (`ClientError`). Trusting that makes a screen render error fields (`code`,
+ * `message`, `request_id`) as columns and breaks producer tracing.
+ *
+ * So we trust `route.success` only when its status is genuinely 2xx; otherwise
+ * we re-pick from the raw operation's 2xx responses ourselves. A `204` (or any
+ * 2xx with no JSON body) correctly yields `null` — no body, not an error body.
+ *
+ * Trusting nestia when it IS 2xx matters: nestia promotes an inline success body
+ * into a named component (`IApiItems.PostResponse`), which the re-pick path (raw
+ * inline object, no `$ref`) cannot reproduce. The status it reports is a STRING
+ * (`"201"`, `"default"`), so we parse it numerically.
+ */
+function pickSuccess(route: {
+  success?: IBodyPart | null;
+  operation: () => OpenApi.IOperation | undefined;
+}): IBodyPart | null {
+  const status = Number(
+    (route.success as { status?: unknown } | null | undefined)?.status,
+  );
+  if (Number.isInteger(status) && status >= 200 && status < 300) {
+    return route.success ?? null;
+  }
+  const responses = route.operation()?.responses ?? {};
+  for (const code of SUCCESS_CODES) {
+    const response = responses[code] as
+      | { description?: string; content?: Record<string, { schema?: unknown }> }
+      | undefined;
+    const schema = response?.content?.["application/json"]?.schema;
+    if (schema !== undefined) {
+      return {
+        type: "application/json",
+        schema: schema as OpenApi.IJsonSchema,
+        description: () => response?.description,
+      };
+    }
+  }
+  return null; // 204 / no JSON body — a genuine empty response, not an error
+}
+
+/**
+ * Operations `HttpMigration` could not turn into a route at all — typically an
+ * unsupported request/response content type (e.g. `application/octet-stream`,
+ * raw binary upload/download). These never reach {@link toEndpoints}, so
+ * surfacing them is the only way to keep the READ layer from dropping
+ * endpoints silently.
+ */
+export interface IUnsupportedOperation {
+  method: string;
+  path: string;
+  reason: string;
+}
+
+export function unsupportedOperations(
+  document: OpenApi.IDocument,
+): IUnsupportedOperation[] {
+  // Same relaxation as toEndpoints, so multi-object-query routes that now
+  // compose are not double-counted here as "dropped".
+  const app = HttpMigration.application(normalizeForNestia(document));
+  const fromErrors = (app.errors ?? []).map((e): IUnsupportedOperation => {
+    const messages: string[] = Array.isArray(e.messages) ? e.messages : [];
+    return {
+      method: (e.method ?? "?").toString().toUpperCase(),
+      path: e.path ?? "?",
+      reason: messages.join("; ") || "unsupported operation",
+    };
+  });
+  // Routes whose accessor is not a valid JS identifier chain (path fragments
+  // like `/shared_items#folders`) are dropped by `toEndpoints` — report them so
+  // nothing vanishes silently.
+  const fromAccessors = app.routes
+    .filter((r) => !isRenderableAccessor(r.accessor))
+    .map((r): IUnsupportedOperation => ({
+      method: r.method.toUpperCase(),
+      path: r.path,
+      reason: `Accessor contains a non-identifier segment (${r.accessor.join(".")}) — cannot generate a typed SDK call.`,
+    }));
+  return [...fromErrors, ...fromAccessors];
+}
+
+interface IBodyPart {
+  type: string;
+  schema: OpenApi.IJsonSchema;
+  description: () => string | undefined;
+}
+
+/**
+ * Resolve a request/response body part into the element type + array flag.
+ * Handles both a named reference (`{ $ref: Pet }` → `Pet`, single) and an
+ * array of references (`{ type: array, items: { $ref: Pet } }` → `Pet`,
+ * isArray) — the latter is the list-response shape the old code dropped,
+ * leaving table screens with no deterministic column source.
+ */
+function resolveBody(
+  part: IBodyPart | null | undefined,
+): IAutoViewEndpoint.IBody | null {
+  if (!part || part.type !== "application/json") return null;
+  const schema = part.schema;
+  if (OpenApiTypeChecker.isReference(schema)) {
+    return {
+      description: part.description() ?? "",
+      typeName: refName(schema.$ref),
+      isArray: false,
+    };
+  }
+  if (OpenApiTypeChecker.isArray(schema)) {
+    const items = schema.items;
+    if (OpenApiTypeChecker.isReference(items)) {
+      return {
+        description: part.description() ?? "",
+        typeName: refName(items.$ref),
+        isArray: true,
+      };
+    }
+  }
+  return null;
+}
+
+function refName($ref: string): string {
+  return $ref.split("/").pop()!;
+}
+
+function writeDescription(
+  operation: OpenApi.IOperation | undefined,
+): string | undefined {
+  if (operation === undefined) return undefined;
+  if (operation.summary === undefined && operation.description === undefined)
+    return undefined;
+  if (operation.summary === undefined) return operation.description;
+  if (operation.description === undefined) return operation.summary;
+  if (operation.description.startsWith(operation.summary))
+    return operation.description;
+  return `${operation.summary}${operation.summary.endsWith(".") ? "" : "."}\n\n${operation.description}`;
+}