@autoview/cli 0.1.0

package/src/utils/resourcePlan.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+
+import { resourcePlan } from "./resourcePlan";
+import { IAutoViewEndpoint } from "./toEndpoints";
+
+const ep = (over: Partial<IAutoViewEndpoint>): IAutoViewEndpoint => ({
+  method: "get",
+  path: "/items",
+  accessor: ["items", "index"],
+  name: "index",
+  description: "",
+  parameters: [],
+  query: null,
+  requestBody: null,
+  responseBody: null,
+  ...over,
+});
+
+describe("resourcePlan — deterministic IA", () => {
+  it("a full-CRUD resource yields list + detail + create + edit", () => {
+    const screens = resourcePlan([
+      ep({ method: "get", path: "/pets", accessor: ["pets", "index"] }),
+      ep({
+        method: "get",
+        path: "/pets/{petId}",
+        accessor: ["pets", "at"],
+        parameters: [{ name: "petId", description: "", schema: { type: "string" } as never }],
+      }),
+      ep({ method: "post", path: "/pets", accessor: ["pets", "create"] }),
+      ep({
+        method: "put",
+        path: "/pets/{petId}",
+        accessor: ["pets", "update"],
+        parameters: [{ name: "petId", description: "", schema: { type: "string" } as never }],
+      }),
+      ep({
+        method: "delete",
+        path: "/pets/{petId}",
+        accessor: ["pets", "erase"],
+        parameters: [{ name: "petId", description: "", schema: { type: "string" } as never }],
+      }),
+    ]);
+    expect(screens.map((s) => s.path)).toEqual([
+      "/pets",
+      "/pets/[petsId]",
+      "/pets/new",
+      "/pets/[petsId]/edit",
+    ]);
+    expect(screens.map((s) => s.kind)).toEqual(["list", "detail", "create", "edit"]);
+    // detail screen hosts update + delete as secondary actions
+    const detail = screens.find((s) => s.kind === "detail")!;
+    expect(detail.secondary.some((c) => c.role === "update")).toBe(true);
+    expect(detail.secondary.some((c) => c.role === "delete")).toBe(true);
+  });
+
+  it("a read-only resource yields only a list screen", () => {
+    const screens = resourcePlan([
+      ep({ method: "get", path: "/inventory", accessor: ["inventory", "index"] }),
+    ]);
+    expect(screens.map((s) => s.kind)).toEqual(["list"]);
+    expect(screens[0]!.path).toBe("/inventory");
+  });
+
+  it("uses a canonical per-resource param name in dynamic routes", () => {
+    const screens = resourcePlan([
+      ep({
+        method: "get",
+        path: "/users/{username}",
+        accessor: ["users", "at"],
+        parameters: [{ name: "username", description: "", schema: { type: "string" } as never }],
+      }),
+    ]);
+    expect(screens[0]!.path).toBe("/users/[usersId]");
+  });
+
+  it("nests a sub-resource under its parent, mirroring the swagger path", () => {
+    const param = (name: string) => ({
+      name,
+      description: "",
+      schema: { type: "string" } as never,
+    });
+    const screens = resourcePlan([
+      // top-level sales
+      ep({ method: "get", path: "/shoppings/admins/sales", accessor: ["shoppings", "admins", "sales", "index"] }),
+      ep({ method: "get", path: "/shoppings/admins/sales/{saleId}", accessor: ["shoppings", "admins", "sales", "at"], parameters: [param("saleId")] }),
+      // nested questions under a sale
+      ep({ method: "get", path: "/shoppings/admins/sales/{saleId}/questions", accessor: ["shoppings", "admins", "sales", "questions", "index"], parameters: [param("saleId")] }),
+      ep({ method: "get", path: "/shoppings/admins/sales/{saleId}/questions/{id}", accessor: ["shoppings", "admins", "sales", "questions", "at"], parameters: [param("saleId"), param("id")] }),
+    ]);
+    const paths = screens.map((s) => s.path);
+    // namespace/actor prefix stripped; sales is top-level (depth 1)
+    expect(paths).toContain("/sales");
+    expect(paths).toContain("/sales/[salesId]");
+    // questions nests under the sale, carrying the parent param in the route
+    expect(paths).toContain("/sales/[salesId]/questions");
+    expect(paths).toContain("/sales/[salesId]/questions/[questionsId]");
+    const questionsList = screens.find((s) => s.path === "/sales/[salesId]/questions")!;
+    expect(questionsList.depth).toBe(2);
+    expect(questionsList.parentPath).toBe("/sales/[salesId]");
+    const salesList = screens.find((s) => s.path === "/sales")!;
+    expect(salesList.depth).toBe(1);
+    expect(salesList.parentPath).toBeNull();
+  });
+});

package/src/utils/resourcePlan.ts

@@ -0,0 +1,180 @@
+import { OpenApi } from "@typia/interface";
+
+import {
+  classifyEndpoints,
+  EndpointRole,
+  IClassifiedEndpoint,
+  IResourceGroup,
+} from "./classifyEndpoints";
+import { IAutoViewEndpoint } from "./toEndpoints";
+
+/**
+ * Deterministic information architecture — the second brick of the "정확한 틀".
+ *
+ * Turns the classified resource groups into a concrete, reproducible screen
+ * set: for each resource, exactly the screens its CRUD roles justify, with real
+ * Next.js paths and the endpoints each screen composes. No LLM, no commerce
+ * baseline, no "5-25 screens, compose, don't enumerate" guesswork — every
+ * resource that exposes a capability gets the corresponding screen, and
+ * nothing more.
+ *
+ * This is what replaces the LLM ProductPlan's IShop-flavored improvisation:
+ * the Render phase later fills these slots with TSX, but the SET of screens is
+ * decided here, structurally.
+ */
+export type ScreenKind = "list" | "detail" | "create" | "edit";
+
+export interface IPlannedScreen {
+  /** Next.js App Router path, dynamic segments in `[brackets]`. */
+  path: string;
+  resource: string;
+  kind: ScreenKind;
+  /** Hierarchy depth: 1 = top-level resource, ≥2 = nested under a parent. */
+  depth: number;
+  /** Parent collection path (`/sales/[saleId]`) for a nested resource, else null. */
+  parentPath: string | null;
+  title: string;
+  /** Primary data-source / target endpoint for the screen. */
+  primary: IAutoViewEndpoint;
+  /**
+   * Secondary endpoints the screen wires in — e.g. a detail screen surfaces
+   * its update / delete / action endpoints as buttons; a list screen links to
+   * detail. Empty for create.
+   */
+  secondary: IClassifiedEndpoint[];
+}
+
+function pick(group: IResourceGroup, role: EndpointRole): IClassifiedEndpoint[] {
+  return group.endpoints.filter((c) => c.role === role);
+}
+
+function titleize(resource: string): string {
+  const spaced = resource.replace(/[_-]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/**
+ * Canonical route param name for a resource: `<name>Id`. Derived from the
+ * resource NAME (not the endpoint's param), so it is identical everywhere the
+ * resource appears (its own detail and as a parent of a sub-resource) and
+ * distinct from every other resource's param. This guarantees a route never has
+ * a sibling-slug conflict (`/sales/[id]` vs `/sales/[saleId]`) nor a repeated
+ * slug within one path (`/sales/[id]/questions/[id]`) — both of which Next.js
+ * rejects at boot. The SDK's own param names are recovered separately by
+ * position when the page issues its fetch.
+ */
+function canonParam(name: string): string {
+  return `${name.replace(/[^A-Za-z0-9]/g, "")}Id`;
+}
+
+/**
+ * The collection route for a resource group, mirroring the swagger hierarchy:
+ * every parent link contributes `<name>/[<canonParam>]`, the leaf its bare name.
+ * `[sales, questions]` → `/sales/[salesId]/questions`. `[sales]` → `/sales`.
+ */
+/** A parent link's route part: `sales/[salesId]` when item-addressed, else just
+ * `coupons` (a path prefix with no `{param}`, so no bracket). */
+function parentPart(link: { name: string; param: string | null }): string {
+  return link.param !== null ? `${link.name}/[${canonParam(link.name)}]` : link.name;
+}
+
+function collectionPath(group: IResourceGroup): string {
+  const links = group.chain;
+  const parts = links.map((c, i) => (i < links.length - 1 ? parentPart(c) : c.name));
+  return `/${parts.join("/")}`;
+}
+
+/** The parent collection path (`/sales/[salesId]`) for a nested group, else null. */
+function parentPathOf(group: IResourceGroup): string | null {
+  if (group.chain.length < 2) return null;
+  const parents = group.chain.slice(0, -1);
+  return `/${parents.map(parentPart).join("/")}`;
+}
+
+/** Item route param for a group's own entity (`/sales` → `[salesId]`). */
+function itemParam(group: IResourceGroup): string {
+  return canonParam(group.resource);
+}
+
+export function planResource(group: IResourceGroup): IPlannedScreen[] {
+  const screens: IPlannedScreen[] = [];
+  const resource = group.resource;
+  const label = titleize(resource);
+  const depth = group.chain.length;
+  const parentPath = parentPathOf(group);
+  const base = collectionPath(group);
+  const common = { resource, depth, parentPath };
+
+  // Prefer the top-level enumeration as the resource's primary list: the real
+  // `/v2/droplets` (no path params) over an id-scoped sub-view that happens to
+  // classify as a list (`/v2/droplets/{id}/destroy_with_associated_resources`),
+  // whose response is NOT the resource's own rows. Fewest path params wins;
+  // stable otherwise (list before search at equal depth).
+  const listish = [...pick(group, "list"), ...pick(group, "search")].sort(
+    (a, b) => a.endpoint.parameters.length - b.endpoint.parameters.length,
+  );
+  const details = pick(group, "detail");
+  const creates = pick(group, "create");
+  const updates = pick(group, "update");
+  const deletes = pick(group, "delete");
+  const actions = pick(group, "action");
+
+  // List / search screen — the resource's home.
+  if (listish.length > 0) {
+    screens.push({
+      ...common,
+      path: base,
+      kind: "list",
+      title: label,
+      primary: listish[0]!.endpoint,
+      // extra search variants + the row-action targets (detail/delete) the
+      // list links to.
+      secondary: [...listish.slice(1), ...details, ...deletes],
+    });
+  }
+
+  // Detail screen — one entity. Hosts update/delete/action as buttons.
+  if (details.length > 0) {
+    screens.push({
+      ...common,
+      path: `${base}/[${itemParam(group)}]`,
+      kind: "detail",
+      title: `${label} detail`,
+      primary: details[0]!.endpoint,
+      secondary: [...updates, ...deletes, ...actions],
+    });
+  }
+
+  // Create screen — a form from the POST requestBody schema.
+  if (creates.length > 0) {
+    screens.push({
+      ...common,
+      path: `${base}/new`,
+      kind: "create",
+      title: `New ${label.toLowerCase()}`,
+      primary: creates[0]!.endpoint,
+      secondary: [],
+    });
+  }
+
+  // Edit screen — a form from the PUT/PATCH requestBody, prefilled by detail.
+  if (updates.length > 0) {
+    screens.push({
+      ...common,
+      path: `${base}/[${itemParam(group)}]/edit`,
+      kind: "edit",
+      title: `Edit ${label.toLowerCase()}`,
+      primary: updates[0]!.endpoint,
+      secondary: details,
+    });
+  }
+
+  return screens;
+}
+
+export function resourcePlan(
+  endpoints: IAutoViewEndpoint[],
+  document?: OpenApi.IDocument,
+): IPlannedScreen[] {
+  return classifyEndpoints(endpoints, document).flatMap(planResource);
+}

package/src/utils/sliceDocument.test.ts

@@ -0,0 +1,85 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { sliceDocument } from "./sliceDocument";
+import { toEndpoints } from "./toEndpoints";
+
+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 objResp = (name: string) => ({
+  200: { description: "ok", content: { "application/json": { schema: { $ref: `#/components/schemas/${name}` } } } },
+});
+
+const fixture = doc(
+  {
+    "/sales": { get: { operationId: "listSales", responses: objResp("Sale") } },
+    "/orders": { get: { operationId: "listOrders", responses: objResp("Order") } },
+  },
+  {
+    // Sale references Seller (transitively kept); Order references nothing extra.
+    Sale: { type: "object", properties: { id: { type: "string" }, seller: { $ref: "#/components/schemas/Seller" } } },
+    Seller: { type: "object", properties: { id: { type: "string" }, name: { type: "string" } } },
+    Order: { type: "object", properties: { id: { type: "string" } } },
+  },
+);
+
+describe("sliceDocument", () => {
+  it("keeps only the included paths", () => {
+    const sliced = sliceDocument(fixture, { include: ["/sales"] });
+    expect(Object.keys(sliced.paths)).toEqual(["/sales"]);
+  });
+
+  it("prunes component schemas to the transitive closure of kept operations", () => {
+    const sliced = sliceDocument(fixture, { include: ["/sales"] });
+    const kept = Object.keys(sliced.components?.schemas ?? {}).sort();
+    // Sale (response) + Seller (referenced by Sale) kept; Order dropped.
+    expect(kept).toEqual(["Sale", "Seller"]);
+  });
+
+  it("drops a path's unincluded sibling methods but keeps included ones", () => {
+    const d = doc(
+      {
+        "/items": {
+          get: { operationId: "list", responses: objResp("Item") },
+        },
+        "/items/{id}": {
+          get: { operationId: "at", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: objResp("Item") },
+        },
+      },
+      { Item: { type: "object", properties: { id: { type: "string" } } } },
+    );
+    const sliced = sliceDocument(d, { exclude: ["/items/**"] });
+    expect(Object.keys(sliced.paths)).toEqual(["/items"]);
+  });
+
+  it("is a no-op when no filter is given (same endpoints)", () => {
+    const sliced = sliceDocument(fixture, {});
+    expect(toEndpoints(sliced).map((e) => e.path).sort()).toEqual(
+      toEndpoints(fixture).map((e) => e.path).sort(),
+    );
+  });
+
+  it("does not mutate the input document", () => {
+    const before = Object.keys(fixture.components?.schemas ?? {}).length;
+    sliceDocument(fixture, { include: ["/sales"] });
+    expect(Object.keys(fixture.components?.schemas ?? {}).length).toBe(before);
+  });
+
+  it("leaves the kept operations renderable end to end", () => {
+    const sliced = sliceDocument(fixture, { include: ["/sales"] });
+    const eps = toEndpoints(sliced);
+    expect(eps).toHaveLength(1);
+    expect(eps[0]!.responseBody?.typeName).toBe("Sale");
+  });
+});

package/src/utils/sliceDocument.ts

@@ -0,0 +1,119 @@
+import { OpenApi } from "@typia/interface";
+
+import { IEndpointFilter, filterEndpoints } from "./endpointFilter";
+import { toEndpoints } from "./toEndpoints";
+
+/**
+ * Slice an OpenAPI document down to an operator-selected surface — the fix for
+ * "`--include` only trims the endpoint list, but the SDK Study still compiles
+ * the WHOLE document and overflows the model's context on a large swagger".
+ *
+ * {@link filterEndpoints} answers *which screens*; this answers *which document*.
+ * It keeps only the filtered paths/methods AND prunes `components.schemas` to
+ * the transitive closure those operations actually reference, so every
+ * downstream phase (SDK Study, Product Plan, Render) sees a document whose size
+ * matches the requested slice — not the original 300-type spec.
+ *
+ * Pure: returns a new document; the input is never mutated. A no-op filter
+ * returns an equivalent document (schemas reachable from all operations).
+ */
+export function sliceDocument(
+  document: OpenApi.IDocument,
+  filter: IEndpointFilter = {},
+): OpenApi.IDocument {
+  const kept = new Set(
+    filterEndpoints(toEndpoints(document), filter).map(
+      (e) => `${e.method.toLowerCase()} ${e.path}`,
+    ),
+  );
+
+  // Rebuild paths, keeping only the (method, path) pairs that survived the
+  // filter. A path with no surviving method is dropped entirely.
+  const paths: Record<string, OpenApi.IPath> = {};
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    if (item === undefined) continue;
+    const keptItem: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(item)) {
+      // Non-method members of a path item (parameters, $ref, summary…) are
+      // carried over only when at least one method on the path survives.
+      if (!HTTP_METHODS.has(key.toLowerCase())) continue;
+      if (kept.has(`${key.toLowerCase()} ${path}`)) keptItem[key] = value;
+    }
+    if (Object.keys(keptItem).length === 0) continue;
+    for (const [key, value] of Object.entries(item)) {
+      if (!HTTP_METHODS.has(key.toLowerCase())) keptItem[key] = value;
+    }
+    paths[path] = keptItem as OpenApi.IPath;
+  }
+
+  // Compute the transitive schema closure reachable from the kept operations.
+  const allSchemas = document.components?.schemas ?? {};
+  const reachable = new Set<string>();
+  const frontier: string[] = [];
+  const seed = (schema: unknown): void => {
+    for (const name of collectRefs(schema)) {
+      if (!reachable.has(name)) {
+        reachable.add(name);
+        frontier.push(name);
+      }
+    }
+  };
+  for (const item of Object.values(paths)) {
+    for (const [key, op] of Object.entries(item ?? {})) {
+      if (!HTTP_METHODS.has(key.toLowerCase())) continue;
+      seed(op);
+    }
+  }
+  while (frontier.length > 0) {
+    const name = frontier.pop()!;
+    seed(allSchemas[name]);
+  }
+
+  const schemas: Record<string, OpenApi.IJsonSchema> = {};
+  for (const name of reachable) {
+    const schema = allSchemas[name];
+    if (schema !== undefined) schemas[name] = schema;
+  }
+
+  return {
+    ...document,
+    paths,
+    components: { ...document.components, schemas },
+  };
+}
+
+const HTTP_METHODS = new Set([
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace",
+]);
+
+/**
+ * Every component name a JSON value references via `$ref`, found by walking the
+ * whole subtree (properties, items, allOf/oneOf/anyOf, additionalProperties,
+ * and arbitrarily nested objects/arrays). Returns bare names (`Sale`), not
+ * pointers.
+ */
+function collectRefs(value: unknown): string[] {
+  const out: string[] = [];
+  const walk = (node: unknown): void => {
+    if (node === null || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const child of node) walk(child);
+      return;
+    }
+    const obj = node as Record<string, unknown>;
+    const ref = obj.$ref;
+    if (typeof ref === "string" && ref.startsWith("#/components/schemas/")) {
+      out.push(ref.slice("#/components/schemas/".length));
+    }
+    for (const child of Object.values(obj)) walk(child);
+  };
+  walk(value);
+  return out;
+}