@autoview/cli 0.1.0

package/src/orchestrate/utils/normalizeProductPlanPaths.ts

@@ -0,0 +1,92 @@
+import { IAutoViewProductPlan } from "../structures/IAutoViewProductPlan";
+
+/**
+ * Normalize Next.js dynamic-segment names inside a product plan so the
+ * generated app router does not blow up with the `"You cannot use different
+ * slug names for the same dynamic path"` error.
+ *
+ * Background: the Product Plan phase routinely emits sibling routes such as
+ * `/sales/[id]` and `/sales/[saleId]/questions`. Next.js refuses to start when
+ * two routes under the same parent disagree on the dynamic-segment name. Rather
+ * than re-running the planner just to fix the slugs, we rewrite every dynamic
+ * segment in place so the first name we saw at a given parent prefix wins.
+ *
+ * The rewrite touches three places that all need to stay in sync:
+ *
+ * - `screens[].path` (and the screens are returned in the same order so the
+ *   Render phase still maps the right TSX to the right route).
+ * - `navigation[].primary` / `navigation[].secondary` (path arrays referencing
+ *   the screens above).
+ * - That's it — `IOmission.target` is a free-form label, not a path, so the
+ *   function leaves it alone.
+ *
+ * Pure. Does not mutate the input.
+ */
+export function normalizeProductPlanPaths(
+  plan: IAutoViewProductPlan,
+): IAutoViewProductPlan {
+  const canonical = new Map<string, string>(); // parentPrefix -> slug name
+  const rewrites = new Map<string, string>(); // original → normalized
+  const normalize = (path: string): string => {
+    const cached = rewrites.get(path);
+    if (cached !== undefined) return cached;
+    const result = normalizeSinglePath(path, canonical);
+    rewrites.set(path, result);
+    return result;
+  };
+
+  // First pass: build the canonical map by walking screens in order.
+  // The first screen that introduces a dynamic segment at a given
+  // parent wins, which matches the operator's mental model when they
+  // scan the plan top-to-bottom.
+  const screens: IAutoViewProductPlan.IScreen[] = plan.screens.map(
+    (screen) => ({
+      ...screen,
+      path: normalize(screen.path),
+    }),
+  );
+
+  // Second pass: rewrite nav references through the same map.
+  const navigation: IAutoViewProductPlan.INavigation[] = plan.navigation.map(
+    (nav) => ({
+      ...nav,
+      primary: nav.primary.map(normalize),
+      secondary: nav.secondary.map(normalize),
+    }),
+  );
+
+  return {
+    screens,
+    navigation,
+    intentionalOmissions: plan.intentionalOmissions,
+  };
+}
+
+function normalizeSinglePath(
+  path: string,
+  canonical: Map<string, string>,
+): string {
+  const segments = path.replace(/^\/+/, "").split("/");
+  if (segments.length === 0 || segments[0] === "") return path;
+  let prefix = "";
+  const out: string[] = [];
+  for (const seg of segments) {
+    const dynamic = /^\[(.+)\]$/.exec(seg);
+    if (dynamic === null) {
+      out.push(seg);
+      prefix = `${prefix}/${seg}`;
+      continue;
+    }
+    const known = canonical.get(prefix);
+    if (known === undefined) {
+      canonical.set(prefix, dynamic[1]!);
+      out.push(seg);
+      prefix = `${prefix}/${seg}`;
+    } else {
+      const normalized = `[${known}]`;
+      out.push(normalized);
+      prefix = `${prefix}/${normalized}`;
+    }
+  }
+  return `/${out.join("/")}`;
+}

package/src/orchestrate/utils/renderJsonSchema.test.ts

@@ -0,0 +1,162 @@
+import { OpenApi } from "@typia/interface";
+import { describe, expect, it } from "vitest";
+
+import { renderJsonSchema, renderNamedSchema } from "./renderJsonSchema";
+
+const doc = (
+  schemas: Record<string, OpenApi.IJsonSchema>,
+): OpenApi.IDocument =>
+  ({
+    operations: [],
+    components: {
+      schemas,
+      securitySchemes: {},
+    },
+  }) as unknown as OpenApi.IDocument;
+
+describe("renderJsonSchema", () => {
+  it("renders flat objects with required + optional markers", () => {
+    expect(
+      renderJsonSchema(
+        {
+          type: "object",
+          description: "",
+          properties: {
+            id: { type: "string", format: "uuid", description: "" },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              description: "",
+            },
+            nickname: { type: "string", description: "" },
+          },
+          required: ["id", "created_at"],
+        },
+        doc({}),
+      ),
+    ).toBe(
+      [
+        "{",
+        "  id: string /* uuid */;",
+        "  created_at: string /* date-time */;",
+        "  nickname?: string;",
+        "}",
+      ].join("\n"),
+    );
+  });
+
+  it("inlines nested $ref objects", () => {
+    expect(
+      renderJsonSchema(
+        { $ref: "#/components/schemas/IAuthorized" },
+        doc({
+          IAuthorized: {
+            type: "object",
+            description: "",
+            properties: {
+              id: { type: "string", description: "" },
+              token: { $ref: "#/components/schemas/IAuthorizationToken" },
+            },
+            required: ["id", "token"],
+          },
+          IAuthorizationToken: {
+            type: "object",
+            description: "",
+            properties: {
+              access: { type: "string", description: "" },
+              refresh: { type: "string", description: "" },
+              expires_in: { type: "integer", description: "" },
+            },
+            required: ["access", "refresh", "expires_in"],
+          },
+        }),
+      ),
+    ).toBe(
+      [
+        "{",
+        "  id: string;",
+        "  token: {",
+        "    access: string;",
+        "    refresh: string;",
+        "    expires_in: number;",
+        "  };",
+        "}",
+      ].join("\n"),
+    );
+  });
+
+  it("renders arrays of literal-string unions for sort grammars", () => {
+    expect(
+      renderJsonSchema(
+        {
+          type: "object",
+          description: "",
+          properties: {
+            sort: {
+              type: "array",
+              description: "",
+              items: {
+                oneOf: [
+                  { const: "created_at.asc", description: "" },
+                  { const: "created_at.desc", description: "" },
+                ],
+              },
+            },
+          },
+          required: ["sort"],
+        },
+        doc({}),
+      ),
+    ).toBe(
+      ["{", '  sort: Array<"created_at.asc" | "created_at.desc">;', "}"].join(
+        "\n",
+      ),
+    );
+  });
+
+  it("degrades object schemas with no properties to an index signature", () => {
+    expect(
+      renderJsonSchema({ type: "object", description: "" } as never, doc({})),
+    ).toBe("{ [key: string]: unknown }");
+  });
+
+  it("degrades array schemas with no items to unknown[]", () => {
+    expect(
+      renderJsonSchema(
+        {
+          type: "object",
+          description: "",
+          properties: {
+            data: { type: "array", description: "" } as never,
+          },
+          required: ["data"],
+        },
+        doc({}),
+      ),
+    ).toBe(["{", "  data: unknown[];", "}"].join("\n"));
+  });
+});
+
+describe("renderNamedSchema", () => {
+  it("falls back to the bare type name when the component is missing", () => {
+    expect(renderNamedSchema("IMissing", doc({}))).toBe("IMissing");
+  });
+
+  it("renders the resolved schema when present", () => {
+    expect(
+      renderNamedSchema(
+        "IFlag",
+        doc({
+          IFlag: {
+            type: "object",
+            description: "",
+            properties: {
+              value: { type: "boolean", description: "" },
+            },
+            required: ["value"],
+          },
+        }),
+      ),
+    ).toBe(["{", "  value: boolean;", "}"].join("\n"));
+  });
+});

package/src/orchestrate/utils/renderJsonSchema.ts

@@ -0,0 +1,133 @@
+import { OpenApi } from "@typia/interface";
+
+/**
+ * Render an OpenAPI schema (or a named schema reference) as a readable,
+ * multi-line TypeScript-shaped string. The output is intended for inclusion in
+ * an LLM prompt where the model has to write a TSX page against an SDK type —
+ * raw OpenAPI JSON forces the model to mentally translate schema indirection
+ * back into TypeScript and it routinely improvises instead of doing the work.
+ *
+ * Nested `$ref` targets are inlined up to a fixed depth so the LLM does not
+ * have to chase indirection. Beyond that depth the bare type name is emitted so
+ * cycles stay finite. Properties are kept in declaration order; optional fields
+ * are suffixed with `?`. String formats (`uuid`, `date-time`, ...) are appended
+ * as a trailing comment so the LLM can still see the semantic when it matters.
+ *
+ * Pure. Does not mutate the document.
+ */
+export function renderJsonSchema(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+): string {
+  return renderSchema(schema, doc, 0);
+}
+
+/**
+ * Look up a schema by its component name and render it. Returns the bare type
+ * name when the schema is missing from `(doc.components?.schemas ?? {})` so callers can
+ * still surface something useful when the document is incomplete.
+ */
+export function renderNamedSchema(
+  typeName: string,
+  doc: OpenApi.IDocument,
+): string {
+  const schema = (doc.components?.schemas ?? {})[typeName];
+  if (schema === undefined) return typeName;
+  return renderJsonSchema(schema, doc);
+}
+
+const MAX_DEPTH = 3;
+const INDENT = "  ";
+
+function renderSchema(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+  depth: number,
+): string {
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    const name = schema.$ref.replace(/^#\/components\/schemas\//, "");
+    if (depth >= MAX_DEPTH) return name;
+    const target = (doc.components?.schemas ?? {})[name];
+    if (target === undefined) return name;
+    return renderSchema(target, doc, depth);
+  }
+  if ("oneOf" in schema) {
+    const parts = schema.oneOf.map((branch) =>
+      renderSchema(branch, doc, depth),
+    );
+    return parts.length > 0 ? parts.join(" | ") : "unknown";
+  }
+  if ("const" in schema) {
+    return JSON.stringify(
+      (schema as OpenApi.IJsonSchema.IConstant).const,
+    );
+  }
+  if (!("type" in schema)) return "unknown";
+  switch (schema.type) {
+    case "boolean":
+      return "boolean";
+    case "integer":
+    case "number":
+      return "number";
+    case "string": {
+      const tagged = formatStringTag(schema);
+      return tagged === null ? "string" : `string /* ${tagged} */`;
+    }
+    case "null":
+      return "null";
+    case "array": {
+      // OpenAPI arrays are `IArray | ITuple`; only `IArray` carries `items`.
+      // Real-world swaggers (Stripe) also ship array schemas with no `items`
+      // at all — degrade to `unknown[]` instead of recursing into `undefined`.
+      if (!("items" in schema) || schema.items == null) {
+        return "unknown[]";
+      }
+      const item = renderSchema(schema.items, doc, depth);
+      return needsArrayWrap(item) ? `Array<${item}>` : `${item}[]`;
+    }
+    case "object":
+      return renderObject(schema, doc, depth);
+  }
+  return "unknown";
+}
+
+function renderObject(
+  schema: OpenApi.IJsonSchema.IObject,
+  doc: OpenApi.IDocument,
+  depth: number,
+): string {
+  // `properties` is nominally required by the schema type, but real-world
+  // swaggers (Stripe) ship `type: "object"` schemas with no `properties`
+  // key — typically a free-form map declared only via
+  // `additionalProperties`. `Object.entries(undefined)` throws, so guard
+  // to a `Record<string, unknown>`-ish placeholder instead of crashing
+  // the whole Render phase.
+  if (schema.properties === undefined || schema.properties === null) {
+    return "{ [key: string]: unknown }";
+  }
+  const entries = Object.entries(schema.properties);
+  if (entries.length === 0) return "{}";
+  if (depth >= MAX_DEPTH) return "{ ... }";
+  const required = new Set(schema.required ?? []);
+  const pad = INDENT.repeat(depth + 1);
+  const closePad = INDENT.repeat(depth);
+  const lines = entries.map(([name, prop]) => {
+    const rendered = renderSchema(prop, doc, depth + 1);
+    const optional = required.has(name) ? "" : "?";
+    return `${pad}${name}${optional}: ${rendered};`;
+  });
+  return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+
+function needsArrayWrap(rendered: string): boolean {
+  if (rendered.includes(" | ")) return true;
+  if (rendered.startsWith("{")) return true;
+  return false;
+}
+
+function formatStringTag(
+  schema: OpenApi.IJsonSchema.IString,
+): string | null {
+  if (typeof schema.format === "string") return schema.format;
+  return null;
+}