@autoview/cli 0.1.0

package/src/utils/endpointFilter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { filterEndpoints } from "./endpointFilter";
+import { IAutoViewEndpoint } from "./toEndpoints";
+
+const ep = (path: string): IAutoViewEndpoint => ({
+  method: "get", path, accessor: path.split("/").filter(Boolean),
+  name: "x", description: "", parameters: [], query: null,
+  requestBody: null, responseBody: null,
+});
+const paths = (eps: IAutoViewEndpoint[]) => eps.map((e) => e.path);
+
+describe("filterEndpoints", () => {
+  const all = [
+    ep("/shoppings/customers/sales"),
+    ep("/shoppings/customers/orders/{id}"),
+    ep("/shoppings/admins/coupons"),
+    ep("/shoppings/sellers/sales"),
+    ep("/monitors/health"),
+  ];
+
+  it("no filter is a no-op", () => {
+    expect(filterEndpoints(all)).toHaveLength(5);
+  });
+  it("include slices to one actor surface with ** across segments", () => {
+    expect(paths(filterEndpoints(all, { include: ["shoppings/customers/**"] }))).toEqual([
+      "/shoppings/customers/sales",
+      "/shoppings/customers/orders/{id}",
+    ]);
+  });
+  it("exclude drops a matching subtree", () => {
+    expect(paths(filterEndpoints(all, { exclude: ["monitors/**"] }))).not.toContain("/monitors/health");
+  });
+  it("include then exclude compose", () => {
+    const r = filterEndpoints(all, {
+      include: ["shoppings/**"],
+      exclude: ["**/admins/**"],
+    });
+    expect(paths(r)).not.toContain("/shoppings/admins/coupons");
+    expect(paths(r)).toContain("/shoppings/customers/sales");
+  });
+  it("single * stays within a segment", () => {
+    // `shoppings/*/sales` matches one segment, not customers/orders/...
+    const r = filterEndpoints(all, { include: ["shoppings/*/sales"] });
+    expect(paths(r).sort()).toEqual([
+      "/shoppings/customers/sales",
+      "/shoppings/sellers/sales",
+    ]);
+  });
+});

package/src/utils/extractFields.test.ts

@@ -0,0 +1,82 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { extractFields } from "./extractFields";
+
+function doc(schemas: Record<string, unknown>) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "t", version: "1.0.0" },
+    paths: {},
+    components: { schemas },
+  } as never);
+}
+
+describe("extractFields — deterministic data contract", () => {
+  it("extracts every property as a typed field with required flag", () => {
+    const d = doc({
+      Pet: {
+        type: "object",
+        required: ["name", "photoUrls"],
+        properties: {
+          id: { type: "integer" },
+          name: { type: "string" },
+          category: { $ref: "#/components/schemas/Category" },
+          photoUrls: { type: "array", items: { type: "string" } },
+          tags: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
+          status: { type: "string", enum: ["available", "pending", "sold"] },
+        },
+      },
+      Category: { type: "object", properties: { id: { type: "integer" } } },
+      Tag: { type: "object", properties: { id: { type: "integer" } } },
+    });
+    const fields = extractFields("Pet", d);
+    const byName = Object.fromEntries(fields.map((f) => [f.name, f]));
+    expect(fields.map((f) => f.name)).toEqual(["id", "name", "category", "photoUrls", "tags", "status"]);
+    expect(byName.name!.required).toBe(true);
+    expect(byName.id!.required).toBe(false);
+    expect(byName.category!).toMatchObject({ kind: "ref", ref: "Category" });
+    expect(byName.photoUrls!).toMatchObject({ kind: "array", itemKind: "string" });
+    expect(byName.tags!).toMatchObject({ kind: "array", ref: "Tag" });
+    expect(byName.status!).toMatchObject({ kind: "enum" });
+    expect(byName.status!.enumValues).toEqual(["available", "pending", "sold"]);
+  });
+
+  it("resolves nullable refs, bare consts, and homogeneous unions", () => {
+    const d = doc({
+      Account: {
+        type: "object",
+        properties: {
+          // nullable ref → ref (not union)
+          member: { oneOf: [{ type: "null" }, { $ref: "#/components/schemas/Member" }] },
+          // bare discriminant const → one-value enum (not unknown)
+          type: { const: "account" },
+          // homogeneous primitive union (ipv4 | ipv6) → that primitive
+          ip: { oneOf: [{ type: "string", format: "ipv4" }, { type: "string", format: "ipv6" }] },
+          // genuine polymorphic ref union → stays union
+          owner: {
+            oneOf: [
+              { $ref: "#/components/schemas/Member" },
+              { $ref: "#/components/schemas/Guest" },
+            ],
+          },
+        },
+      },
+      Member: { type: "object", properties: { id: { type: "integer" } } },
+      Guest: { type: "object", properties: { id: { type: "integer" } } },
+    });
+    const byName = Object.fromEntries(
+      extractFields("Account", d).map((f) => [f.name, f]),
+    );
+    expect(byName.member!).toMatchObject({ kind: "ref", ref: "Member" });
+    expect(byName.type!).toMatchObject({ kind: "enum", enumValues: ["account"] });
+    expect(byName.ip!).toMatchObject({ kind: "string", format: "ipv4" });
+    expect(byName.owner!.kind).toBe("union");
+  });
+
+  it("returns [] for unknown or property-less types (graceful degrade)", () => {
+    const d = doc({ Free: { type: "object", additionalProperties: true } });
+    expect(extractFields("Free", d)).toEqual([]);
+    expect(extractFields("Missing", d)).toEqual([]);
+  });
+});

package/src/utils/extractFields.ts

@@ -0,0 +1,306 @@
+import { OpenApi } from "@typia/interface";
+
+/**
+ * Deterministic data contract — the field list a screen renders.
+ *
+ * Derived structurally from a component schema's properties: list table
+ * columns, detail rows, and form inputs all come from here instead of the LLM
+ * guessing. This is what makes "table 엄청 적게" structurally impossible — every
+ * property of the row/response/request type becomes a column/row/input.
+ */
+export type FieldKind =
+  | "string"
+  | "number"
+  | "boolean"
+  | "enum"
+  | "array"
+  | "object"
+  | "ref"
+  | "union"
+  | "unknown";
+
+export interface IFieldSpec {
+  name: string;
+  required: boolean;
+  kind: FieldKind;
+  /** String format (`uuid`, `date-time`, `uri`, ...) when present. */
+  format?: string;
+  /** Allowed values for an `enum` field. */
+  enumValues?: Array<string | number | boolean>;
+  /** Component type name for a `ref` field, or the element type of an `array`. */
+  ref?: string;
+  /** For an `array`, the element's kind (e.g. array of strings vs array of refs). */
+  itemKind?: FieldKind;
+  /** For an `array` of primitives, the element's string format (`uri`, …). A
+   *  `string[]` of image URLs carries `format: "uri"` on the ITEM, not the
+   *  array, so the signal is lost without preserving it here. */
+  itemFormat?: string;
+  /**
+   * For an `array` whose elements are an INLINE object (no `$ref`, so {@link ref}
+   * is undefined), the element's own field list — e.g. DigitalOcean's
+   * `{ droplets: [ { id, name, … } ] }`, where the droplet shape is inline. Lets
+   * a table render real columns for such collections instead of one opaque cell.
+   */
+  itemFields?: IFieldSpec[];
+}
+
+function refName($ref: string): string {
+  return $ref.split("/").pop()!;
+}
+
+/**
+ * Field names a paginated/collection response uses to hold its array of items.
+ * `data` is the nestia/AutoBE convention; real APIs vary (Box uses `entries`,
+ * others `items` / `results`). Recognizing all of them lets a list endpoint be
+ * rendered as a table off its element type instead of a one-record detail.
+ */
+export const COLLECTION_FIELD_NAMES = new Set([
+  "data",
+  "entries",
+  "items",
+  "results",
+  "values",
+  "list",
+  "records",
+  "rows",
+]);
+
+/** The array field that holds a collection response's items, if any. */
+export function findCollectionField(
+  fields: IFieldSpec[],
+): IFieldSpec | undefined {
+  return fields.find(
+    (f) => f.kind === "array" && COLLECTION_FIELD_NAMES.has(f.name.toLowerCase()),
+  );
+}
+
+function kindOf(schema: OpenApi.IJsonSchema): {
+  kind: FieldKind;
+  format?: string;
+  enumValues?: Array<string | number | boolean>;
+  ref?: string;
+  itemKind?: FieldKind;
+  itemFormat?: string;
+} {
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    return { kind: "ref", ref: refName(schema.$ref) };
+  }
+  // A bare `const` (no `oneOf`) is a single-value literal — typically a
+  // discriminant like `{ const: "customer" }`. Treat it as a one-value enum so
+  // it renders as a labeled value, not `unknown`.
+  if ("const" in schema && !("oneOf" in schema)) {
+    return {
+      kind: "enum",
+      enumValues: [(schema as { const: string | number | boolean }).const],
+    };
+  }
+  // upgradeDocument normalizes a string enum into `oneOf: [{ const }, ...]`, and
+  // a nullable type into `oneOf: [{ type: "null" }, <real schema>]`. Drop the
+  // null branch first, then: an all-`const` set is an enum; a single remaining
+  // branch is just that type made nullable (unwrap it — a nullable `$ref`
+  // becomes a `ref`, not a `union`); anything else is a real union.
+  if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
+    const branches = schema.oneOf.filter(
+      (b) => !("type" in b && (b as { type?: unknown }).type === "null"),
+    );
+    const consts = branches.map((b) =>
+      "const" in b ? (b.const as string | number) : undefined,
+    );
+    if (consts.length > 0 && consts.every((c) => c !== undefined)) {
+      return { kind: "enum", enumValues: consts as Array<string | number> };
+    }
+    if (branches.length === 1) return kindOf(branches[0]!);
+    // A homogeneous primitive union (e.g. a string that is `ipv4 | ipv6`, or
+    // `uri | ""`) is, for display, just that primitive — collapse it. Branches
+    // with differing or no `type` (a real polymorphic `$ref` union) stay
+    // `union` so we never mislabel one variant as another.
+    const prims = branches.map((b) =>
+      "type" in b ? (b as { type?: unknown }).type : undefined,
+    );
+    if (prims.every((t) => t !== undefined && t === prims[0])) {
+      return kindOf(branches[0]!);
+    }
+    return { kind: "union" };
+  }
+  if ("anyOf" in schema || "allOf" in schema) {
+    return { kind: "union" };
+  }
+  if (!("type" in schema)) return { kind: "unknown" };
+  switch (schema.type) {
+    case "boolean":
+      return { kind: "boolean" };
+    case "integer":
+    case "number":
+      return { kind: "number" };
+    case "string": {
+      // biome-ignore lint: enum is part of the JSON Schema string node
+      const enumValues = (schema as { enum?: Array<string | number> }).enum;
+      if (Array.isArray(enumValues) && enumValues.length > 0) {
+        return { kind: "enum", enumValues, format: schema.format };
+      }
+      return { kind: "string", format: schema.format };
+    }
+    case "array": {
+      const items = "items" in schema ? schema.items : undefined;
+      if (items === undefined) return { kind: "array", itemKind: "unknown" };
+      const inner = kindOf(items);
+      return {
+        kind: "array",
+        itemKind: inner.kind,
+        ref: inner.ref,
+        itemFormat: inner.format,
+      };
+    }
+    case "object":
+      return { kind: "object" };
+    default:
+      return { kind: "unknown" };
+  }
+}
+
+/**
+ * Resolve a schema's effective `{ properties, required }`, following `$ref` and
+ * merging every `allOf` member. Composition (`allOf`) is a core OpenAPI feature
+ * real swaggers (Box, Stripe, …) lean on heavily — a type is often
+ * `allOf: [BasePagination, { properties: { entries } }]` with no direct
+ * `properties` of its own. Without this, such a type renders zero fields.
+ *
+ * Own `properties` win over inherited ones on a name clash; `required` is the
+ * union. Depth-guarded against cyclic `$ref`.
+ */
+export function resolveProperties(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+  depth = 0,
+): { properties: Record<string, OpenApi.IJsonSchema>; required: string[] } {
+  if (depth > 8) return { properties: {}, required: [] };
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    const target = (doc.components?.schemas ?? {})[refName(schema.$ref)];
+    return target === undefined
+      ? { properties: {}, required: [] }
+      : resolveProperties(target, doc, depth + 1);
+  }
+  let properties: Record<string, OpenApi.IJsonSchema> = {};
+  let required: string[] = [];
+  if ("allOf" in schema && Array.isArray(schema.allOf)) {
+    for (const member of schema.allOf) {
+      const sub = resolveProperties(member, doc, depth + 1);
+      properties = { ...properties, ...sub.properties };
+      required = [...required, ...sub.required];
+    }
+  }
+  if ("properties" in schema && schema.properties !== undefined) {
+    properties = { ...properties, ...schema.properties };
+  }
+  if ("required" in schema && Array.isArray(schema.required)) {
+    required = [...required, ...schema.required];
+  }
+  return { properties, required: [...new Set(required)] };
+}
+
+/**
+ * Extract the field list of a schema directly (resolving `$ref` and `allOf`).
+ * Works for both named component schemas and INLINE schemas — e.g. a response
+ * `{ databases: T[], links: … }` that is not a named component (common on
+ * DigitalOcean). Returns `[]` when there are no resolvable `properties`.
+ */
+export function extractFieldsFromSchema(
+  schema: OpenApi.IJsonSchema,
+  document: OpenApi.IDocument,
+): IFieldSpec[] {
+  const { properties, required } = resolveProperties(schema, document, 0);
+  const requiredSet = new Set(required);
+  return Object.entries(properties).map(([name, prop]) => {
+    const k = kindOf(prop);
+    // For an array of INLINE objects (no $ref element type), resolve the
+    // element's own fields so a table can show its columns.
+    let itemFields: IFieldSpec[] | undefined;
+    if (k.kind === "array" && k.ref === undefined) {
+      const items = (prop as { items?: OpenApi.IJsonSchema }).items;
+      if (items !== undefined) {
+        const inner = extractFieldsFromSchema(items, document);
+        if (inner.length > 0) itemFields = inner;
+      }
+    }
+    return {
+      name,
+      required: requiredSet.has(name),
+      kind: k.kind,
+      format: k.format,
+      enumValues: k.enumValues,
+      ref: k.ref,
+      itemKind: k.itemKind,
+      itemFormat: k.itemFormat,
+      itemFields,
+    };
+  });
+}
+
+/**
+ * Extract the field list of a NAMED component schema. Returns `[]` when the type
+ * is unknown or has no resolvable `properties` — the caller then degrades
+ * gracefully rather than inventing fields.
+ */
+export function extractFields(
+  typeName: string,
+  document: OpenApi.IDocument,
+): IFieldSpec[] {
+  const schema = (document.components?.schemas ?? {})[typeName];
+  if (schema === undefined) return [];
+  return extractFieldsFromSchema(schema, document);
+}
+
+/** Field names that read as an image, optionally suffixed with url(s)/uri(s)/src. */
+const IMAGE_NAME =
+  /(image|img|photo|picture|thumbnail|thumb|avatar|icon|logo|banner|cover|poster|artwork)s?(_?(url|uri|src|href)s?)?$/i;
+/** Field names that hold a human title for a record (the card's heading). */
+const TITLE_NAMES = new Set([
+  "name",
+  "title",
+  "label",
+  "headline",
+  "subject",
+  "nickname",
+]);
+
+/**
+ * The field that best represents a record's image, or `undefined`. A scalar
+ * `string` (often `format: uri`) or a `string[]` of image URLs whose NAME reads
+ * as an image wins; failing that, a uri-formatted url-ish field. This is the
+ * signal that turns a list into a catalog of cards instead of a table.
+ */
+export function imageFieldOf(columns: IFieldSpec[]): IFieldSpec | undefined {
+  const named = columns.find(
+    (c) =>
+      IMAGE_NAME.test(c.name) &&
+      (c.kind === "string" || (c.kind === "array" && c.itemKind === "string")),
+  );
+  if (named !== undefined) return named;
+  return columns.find(
+    (c) =>
+      (c.kind === "string" &&
+        c.format === "uri" &&
+        /url|uri|src|link/i.test(c.name)) ||
+      (c.kind === "array" && c.itemKind === "string" && c.itemFormat === "uri"),
+  );
+}
+
+/** The field that best titles a record (a card's heading), or `undefined`. */
+export function titleFieldOf(columns: IFieldSpec[]): IFieldSpec | undefined {
+  return (
+    columns.find(
+      (c) => c.kind === "string" && TITLE_NAMES.has(c.name.toLowerCase()),
+    ) ?? columns.find((c) => c.kind === "string" && /name|title/i.test(c.name))
+  );
+}
+
+/**
+ * A collection deserves a catalog (card grid) rather than a table when its rows
+ * carry both an image and a title — the two things a card needs. Purely
+ * structural from the element schema; no domain keywords.
+ */
+export function isCatalogCollection(columns: IFieldSpec[]): boolean {
+  return (
+    imageFieldOf(columns) !== undefined && titleFieldOf(columns) !== undefined
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Self-contained replacements for the `@autobe/utils` surface this package
+ * uses. Migrated 2026-06-01 as Step 2 of the AutoBE-independence track — the
+ * underlying conversions still rely on the typia / nestia ecosystem
+ * (`@typia/utils`, `@typia/interface`), which are not AutoBE packages.
+ */
+export * from "./StringUtil";
+export * from "./ArrayUtil";
+export * from "./toEndpoints";
+export * from "./classifyEndpoints";
+export * from "./endpointFilter";
+export * from "./extractFields";
+export * from "./resourcePlan";

package/src/utils/normalizeForNestia.test.ts

@@ -0,0 +1,93 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { normalizeForNestia } from "./normalizeForNestia";
+
+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 op = (d: ReturnType<typeof doc>, path: string, method: string) =>
+  // biome-ignore lint: structural access to the normalized path item
+  (d.paths as Record<string, Record<string, { requestBody?: unknown; parameters?: { in: string }[] }>>)[
+    path
+  ]?.[method];
+
+describe("normalizeForNestia", () => {
+  it("strips a requestBody from a GET operation (invalid HTTP nestia would mis-generate)", () => {
+    // Notion's `GET /v1/comments` declares an x-www-form-urlencoded requestBody.
+    // nestia faithfully emits a GET SDK function carrying a request body, which
+    // its own typed fetcher (body only on DELETE/POST/PUT/PATCH) then rejects.
+    const d = doc({
+      "/v1/comments": {
+        get: {
+          operationId: "comments",
+          requestBody: {
+            content: {
+              "application/x-www-form-urlencoded": {
+                schema: { type: "object", properties: { q: { type: "string" } } },
+              },
+            },
+          },
+          responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/X" } } } } },
+        },
+      },
+    }, { X: { type: "object", properties: { id: { type: "string" } } } });
+    const out = normalizeForNestia(d);
+    expect(op(out, "/v1/comments", "get")?.requestBody).toBeUndefined();
+  });
+
+  it("keeps a requestBody on a POST operation (body is valid there)", () => {
+    const d = doc({
+      "/items": {
+        post: {
+          operationId: "create",
+          requestBody: { content: { "application/json": { schema: { type: "object", properties: { name: { type: "string" } } } } } },
+          responses: { 201: { description: "created", content: { "application/json": { schema: { $ref: "#/components/schemas/X" } } } } },
+        },
+      },
+    }, { X: { type: "object", properties: { id: { type: "string" } } } });
+    const out = normalizeForNestia(d);
+    expect(op(out, "/items", "post")?.requestBody).toBeDefined();
+  });
+
+  it("drops all but the first object-typed query param (the dropped-list fix)", () => {
+    const d = doc({
+      "/accounting/invoices": {
+        get: {
+          operationId: "invoicesAll",
+          parameters: [
+            { name: "filter", in: "query", schema: { $ref: "#/components/schemas/F" } },
+            { name: "sort", in: "query", schema: { type: "object", properties: { by: { type: "string" } } } },
+            { name: "limit", in: "query", schema: { type: "integer" } },
+          ],
+          responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/X" } } } } },
+        },
+      },
+    }, {
+      X: { type: "object", properties: { id: { type: "string" } } },
+      F: { type: "object", properties: { n: { type: "string" } } },
+    });
+    const out = normalizeForNestia(d);
+    const params = op(out, "/accounting/invoices", "get")?.parameters ?? [];
+    const objectQuery = params.filter((p) => p.in === "query").length;
+    // filter (object) + limit (primitive) survive; sort (2nd object) is dropped.
+    expect(objectQuery).toBe(2);
+  });
+
+  it("returns the same document reference when nothing needs normalizing", () => {
+    const d = doc({
+      "/items": { get: { operationId: "list", responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/X" } } } } } } },
+    }, { X: { type: "object", properties: { id: { type: "string" } } } });
+    expect(normalizeForNestia(d)).toBe(d);
+  });
+});

package/src/utils/normalizeForNestia.ts

@@ -0,0 +1,139 @@
+import { OpenApi } from "@typia/interface";
+import { OpenApiTypeChecker } from "@typia/utils";
+
+/**
+ * Normalize a real-world OpenAPI document so nestia (`HttpMigration` and
+ * `@nestia/migrate`) can turn EVERY operation into a compilable typed route.
+ * Real swaggers carry shapes that nestia faithfully reproduces but its own typed
+ * fetcher then rejects (or refuses to emit), silently dropping screens and SDK
+ * functions. This pass rewrites only those shapes — additively, never removing a
+ * route that already worked — and is applied identically by the READ layer
+ * (`toEndpoints`) and the SDK compiler so the screen plan and the SDK stay in
+ * lockstep.
+ *
+ * Two corrections, both seen in the wild:
+ *
+ * 1. **Multi-object query → dropped route.** nestia drops an entire route when
+ *    its query has more than one 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 that produces ids for navigation. We keep only the
+ *    first object-typed query param; AutoView rebuilds the complete query from
+ *    the untouched original document (`buildQuerySchema`) and the list page
+ *    casts its query argument, so nothing the UI sees is lost.
+ *
+ * 2. **Body on a GET/HEAD → uncompilable SDK.** Notion's `GET /v1/comments` and
+ *    `GET /v1/users/{id}` declare an `application/x-www-form-urlencoded`
+ *    requestBody. A body on GET/HEAD is invalid HTTP; nestia still emits a GET
+ *    SDK function carrying a request body, which its fetcher (body only on
+ *    DELETE/POST/PUT/PATCH) rejects — a hard type error that also leaves those
+ *    pages empty at runtime. We strip the requestBody from GET/HEAD operations.
+ *
+ * Pure: the input document is never mutated. Only operations that actually need
+ * a correction are rebuilt; everything else is shared by reference, and a
+ * document needing no correction is returned as-is (same reference).
+ */
+export function normalizeForNestia(
+  document: OpenApi.IDocument,
+): OpenApi.IDocument {
+  const paths = document.paths ?? {};
+  let changed = false;
+  const nextPaths: Record<string, unknown> = {};
+  for (const [path, item] of Object.entries(paths)) {
+    const relaxed = normalizePathItem(item as Record<string, unknown>, document);
+    nextPaths[path] = relaxed.item;
+    changed = changed || relaxed.changed;
+  }
+  if (!changed) return document;
+  // biome-ignore lint: structurally an OpenApi.IDocument with a rebuilt paths map
+  return { ...document, paths: nextPaths } as OpenApi.IDocument;
+}
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head"] as const;
+
+/** HTTP methods whose request body nestia's typed fetcher cannot carry. */
+const BODYLESS_METHODS = new Set(["get", "head"]);
+
+function normalizePathItem(
+  item: Record<string, unknown>,
+  document: OpenApi.IDocument,
+): { item: Record<string, unknown>; changed: boolean } {
+  let changed = false;
+  const next: Record<string, unknown> = { ...item };
+  for (const method of HTTP_METHODS) {
+    const op = item[method] as OpenApi.IOperation | undefined;
+    if (op === undefined) continue;
+    const normalized = normalizeOperation(op, method, document);
+    if (normalized !== op) {
+      next[method] = normalized;
+      changed = true;
+    }
+  }
+  return changed ? { item: next, changed } : { item, changed: false };
+}
+
+function normalizeOperation(
+  operation: OpenApi.IOperation,
+  method: string,
+  document: OpenApi.IDocument,
+): OpenApi.IOperation {
+  let next = operation;
+  next = stripBodyFromBodylessMethod(next, method);
+  next = relaxMultiObjectQuery(next, document);
+  return next;
+}
+
+/**
+ * Remove the requestBody from a GET/HEAD operation — a body is invalid there and
+ * makes nestia emit an SDK function its own fetcher rejects.
+ */
+function stripBodyFromBodylessMethod(
+  operation: OpenApi.IOperation,
+  method: string,
+): OpenApi.IOperation {
+  if (!BODYLESS_METHODS.has(method)) return operation;
+  if (operation.requestBody === undefined) return operation;
+  const { requestBody: _dropped, ...rest } = operation as OpenApi.IOperation & {
+    requestBody?: unknown;
+  };
+  return rest as OpenApi.IOperation;
+}
+
+/**
+ * Keep only the first object-typed query parameter, or return the operation
+ * unchanged when it has ≤1 such param.
+ */
+function relaxMultiObjectQuery(
+  operation: OpenApi.IOperation,
+  document: OpenApi.IDocument,
+): OpenApi.IOperation {
+  const params = operation.parameters;
+  if (!Array.isArray(params)) return operation;
+  const objectQueryIndexes = params
+    .map((p, i) =>
+      p.in === "query" && isObjectQuerySchema(p.schema, document) ? i : -1,
+    )
+    .filter((i) => i >= 0);
+  if (objectQueryIndexes.length <= 1) return operation;
+  const drop = new Set(objectQueryIndexes.slice(1));
+  return { ...operation, parameters: params.filter((_, i) => !drop.has(i)) };
+}
+
+/**
+ * Mirror of the composer's object test (HttpMigrateRouteComposer): a query param
+ * counts as an "object" when its schema is an object, or a `$ref` to a component
+ * schema that is an object.
+ */
+function isObjectQuerySchema(
+  schema: OpenApi.IJsonSchema | undefined,
+  document: OpenApi.IDocument,
+): boolean {
+  if (schema === undefined) return false;
+  if (OpenApiTypeChecker.isObject(schema)) return true;
+  if (OpenApiTypeChecker.isReference(schema)) {
+    const name = schema.$ref.split("/").pop() ?? "";
+    const target = (document.components?.schemas ?? {})[name];
+    return target !== undefined && OpenApiTypeChecker.isObject(target);
+  }
+  return false;
+}