@autoview/cli 0.1.0

package/src/typings/events.ts

@@ -0,0 +1,155 @@
+import { tags } from "typia";
+
+import { AutoBeFunctionCallingMetric } from "./misc";
+import { IAutoBeTokenUsageJson } from "./misc";
+
+/**
+ * Base shape shared by every AutoView event.
+ *
+ * Self-defined (formerly `AutoBeEventBase` from `@autobe/interface`) so this
+ * package carries no AutoBE dependency. The standalone AutoView agent only
+ * emits the seven events below, so the base is reproduced here verbatim rather
+ * than importing the full AutoBE event hierarchy.
+ */
+export interface AutoBeEventBase<Type extends string> {
+  /** A unique identifier for the event. */
+  id: string;
+
+  /** Literal discriminator for the event type. */
+  type: Type;
+
+  /** ISO-8601 timestamp of when the event was emitted. */
+  created_at: string & tags.Format<"date-time">;
+}
+
+/**
+ * Event sources surfaced by the agent's `conversate` calls — only the phases
+ * that actually invoke the LLM are represented (scaffold / start / complete
+ * are deterministic and never appear as a source).
+ */
+export type AutoBeEventSource =
+  | "autoViewSdkStudy"
+  | "autoViewProductPlan"
+  | "autoViewRenderPage"
+  | "autoViewReview";
+
+/** Fired once when an AutoView run begins. */
+export interface AutoBeAutoViewStartEvent
+  extends AutoBeEventBase<"autoViewStart"> {
+  /** SDK source the run is built against. */
+  source: "interface" | "shopping";
+
+  /** Step counter of the interface phase this run is based on (`0` for shopping). */
+  step: number;
+
+  /** Optional design-theme instruction forwarded to plan + render phases. */
+  designTheme: string;
+
+  /** Human-readable reason the run was triggered. */
+  reason: string;
+}
+
+/** Fired when Phase 1 (SDK Study) produces the domain map. */
+export interface AutoBeAutoViewSdkStudyEvent
+  extends AutoBeEventBase<"autoViewSdkStudy"> {
+  step: number;
+
+  /** Number of resources surfaced in the SDK map. */
+  resources: number;
+
+  /** Number of actors surfaced in the SDK map. */
+  actors: number;
+
+  /** Rendered SDK domain-map markdown. */
+  sdkMap: string;
+}
+
+/** Fired when Phase 2 (Product Plan) produces the screen IA. */
+export interface AutoBeAutoViewProductPlanEvent
+  extends AutoBeEventBase<"autoViewProductPlan"> {
+  step: number;
+
+  /** Number of planned screens. */
+  pages: number;
+
+  /** Number of intentionally omitted screens. */
+  intentionalOmissions: number;
+
+  /** Rendered product-plan markdown. */
+  productPlan: string;
+}
+
+/** Fired when Phase 3 (Scaffold) finishes writing the deterministic skeleton. */
+export interface AutoBeAutoViewScaffoldEvent
+  extends AutoBeEventBase<"autoViewScaffold"> {
+  step: number;
+
+  /** Number of scaffolded files. */
+  files: number;
+}
+
+/** Fired once per page during Phase 4 (Render). */
+export interface AutoBeAutoViewRenderPageEvent
+  extends AutoBeEventBase<"autoViewRenderPage"> {
+  step: number;
+
+  /** Total number of pages to render. */
+  total: number;
+
+  /** Number of pages completed so far (this one inclusive). */
+  completed: number;
+
+  /** Route path of the rendered page. */
+  pagePath: string;
+
+  /** UI pattern the planner assigned to this screen. */
+  uiPattern: string;
+
+  /** Number of render attempts spent on this page. */
+  attempts: number;
+
+  /** Whether the page rendered + parsed successfully. */
+  ok: boolean;
+
+  /** Token usage spent rendering this page. */
+  tokenUsage: IAutoBeTokenUsageJson.IComponent;
+
+  /** Function-calling metric for this page's render. */
+  metric: AutoBeFunctionCallingMetric;
+}
+
+/** Fired when Phase 5 (UI Review) finishes the code-and-spec audit. */
+export interface AutoBeAutoViewReviewEvent
+  extends AutoBeEventBase<"autoViewReview"> {
+  step: number;
+
+  /** Number of screenshots taken (`0` in the standalone code-review path). */
+  screenshots: number;
+
+  /** Number of pages flagged broken. */
+  broken: number;
+
+  /** Number of broken pages recovered by re-render. */
+  recovered: number;
+
+  /** Rendered SDK-feedback markdown. */
+  sdkFeedback: string;
+}
+
+/** Fired once when an AutoView run completes; carries the assembled files. */
+export interface AutoBeAutoViewCompleteEvent
+  extends AutoBeEventBase<"autoViewComplete"> {
+  step: number;
+
+  /** SDK source the run was built against. */
+  source: "interface" | "shopping";
+
+  /** Wall-clock duration of the run in milliseconds. */
+  elapsed: number;
+
+  /** Number of pages in the finished project. */
+  pages: number;
+
+  /** Final `path → content` map of the generated frontend. */
+  files: Record<string, string>;
+}

package/src/typings/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Self-contained type surface that replaces the `@autobe/interface` import in
+ * this package. Re-exports only what the AutoView agent uses, so the package
+ * carries no `@autobe/*` type dependency.
+ *
+ * Migrated 2026-06-01 as Step 1 of the AutoBE-independence track.
+ */
+export * from "./events";
+export * from "./misc";
+export * from "./compiler";

package/src/typings/misc.ts

@@ -0,0 +1,93 @@
+/**
+ * Minimal self-defined replacements for the handful of `@autobe/interface`
+ * support types the AutoView agent touches. Only the surface the agent
+ * actually reads is reproduced — the full AutoBE definitions carry deep
+ * dependency trees this standalone package has no reason to vendor.
+ */
+
+/** Function-calling metric accumulated across one `conversate` call. */
+export interface AutoBeFunctionCallingMetric {
+  /** Number of LLM call attempts. */
+  attempt: number;
+
+  /** Number of successful tool executions. */
+  success: number;
+
+  /** Number of consent (re-ask) rounds. */
+  consent: number;
+
+  /** Number of schema-validation failures. */
+  validationFailure: number;
+
+  /** Number of invalid-JSON parse failures. */
+  invalidJson: number;
+}
+
+/**
+ * Token-usage shapes. AutoView only ever constructs / forwards
+ * {@link IAutoBeTokenUsageJson.IComponent}, so only that member is defined.
+ */
+export namespace IAutoBeTokenUsageJson {
+  /** Aggregate token usage for a single component. */
+  export interface IComponent {
+    /** Total tokens (input + output). */
+    total: number;
+
+    /** Input-side token breakdown. */
+    input: IInput;
+
+    /** Output-side token breakdown. */
+    output: IOutput;
+  }
+
+  export interface IInput {
+    total: number;
+    cached: number;
+  }
+
+  export interface IOutput {
+    total: number;
+    reasoning: number;
+    accepted_prediction: number;
+    rejected_prediction: number;
+  }
+}
+
+/**
+ * Options accepted by `orchestrateAutoView`. All optional — the orchestrator
+ * fills sensible defaults (interface source, empty theme, simulator backend,
+ * no runtime audit).
+ */
+export interface IAutoBeRunAutoViewOptions {
+  /** SDK source for the run. Defaults to `"interface"`. */
+  source?: "interface" | "shopping";
+
+  /** Design-theme instruction forwarded to plan + render phases. */
+  designTheme?: string;
+
+  /** Live backend host wired into `connection.ts`. `null` → simulator mode. */
+  backend?: { host: string } | null;
+
+  /** Opt into Phase 6 Playwright runtime audit. Defaults to `false`. */
+  runtimeAudit?: boolean;
+
+  /**
+   * Opt into the workflow verification phase: after typecheck, boot the
+   * generated app in a real headless browser and walk the derived user
+   * workflows (list → detail, forms, landing) with positive assertions, writing
+   * `wiki/verification.md`. Proves the app actually works for a user, not just
+   * that it compiles. Heavy (installs Chromium, boots `next dev`); defaults to
+   * `false`.
+   */
+  verify?: boolean;
+
+  /**
+   * Path globs to KEEP — only endpoints whose path matches are turned into
+   * screens. Slices a large swagger to one actor surface, e.g.
+   * `["shoppings/customers/**"]`. Empty/absent means "all".
+   */
+  include?: string[];
+
+  /** Path globs to DROP after include, e.g. `["**​/monitors/**"]`. */
+  exclude?: string[];
+}

package/src/utils/ArrayUtil.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal self-defined replacement for `@autobe/utils`'s `ArrayUtil`. The
+ * self-defined interface compiler only needs `asyncMap` (ordered, sequential
+ * async map), so only that is reproduced.
+ */
+export namespace ArrayUtil {
+  export async function asyncMap<T, U>(
+    array: T[],
+    callback: (value: T, index: number, array: T[]) => Promise<U>,
+  ): Promise<U[]> {
+    const result: U[] = new Array(array.length);
+    for (let i = 0; i < array.length; i++)
+      result[i] = await callback(array[i], i, array);
+    return result;
+  }
+}

package/src/utils/StringUtil.ts

@@ -0,0 +1,29 @@
+import { dedent } from "@typia/utils";
+
+/**
+ * Minimal self-defined replacement for `@autobe/utils`'s `StringUtil`. The
+ * AutoView agent only uses `trim` (template-literal dedent), so only that is
+ * reproduced — `dedent` itself still comes from the typia ecosystem, which is
+ * not an AutoBE dependency.
+ */
+export namespace StringUtil {
+  export function trim(
+    strings: TemplateStringsArray,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ...values: any[]
+  ): string {
+    return dedent(strings, ...values);
+  }
+
+  /** First sentence / first line of a description, whichever comes first. */
+  export function summary(description: string): string {
+    const newLine: number = description.indexOf("\n");
+    const dot: number = description.indexOf(".");
+    const minimum: number = Math.min(
+      newLine === -1 ? Number.MAX_SAFE_INTEGER : newLine,
+      dot === -1 ? Number.MAX_SAFE_INTEGER : dot,
+      description.length,
+    );
+    return description.substring(0, minimum);
+  }
+}

package/src/utils/classifyEndpoints.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyEndpoint, classifyEndpoints } from "./classifyEndpoints";
+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("classifyEndpoint — deterministic CRUD roles", () => {
+  it("GET collection → list", () => {
+    expect(classifyEndpoint(ep({ method: "get", path: "/items" })).role).toBe("list");
+  });
+  it("GET collection with query → search", () => {
+    expect(
+      classifyEndpoint(ep({ method: "get", path: "/items", query: { type: "object" } as never })).role,
+    ).toBe("search");
+  });
+  it("GET item → detail", () => {
+    expect(classifyEndpoint(ep({ method: "get", path: "/items/{id}" })).role).toBe("detail");
+  });
+  it("POST collection → create", () => {
+    expect(classifyEndpoint(ep({ method: "post", path: "/items" })).role).toBe("create");
+  });
+  it("PUT/PATCH item → update", () => {
+    expect(classifyEndpoint(ep({ method: "put", path: "/items/{id}" })).role).toBe("update");
+    expect(classifyEndpoint(ep({ method: "patch", path: "/items/{id}" })).role).toBe("update");
+  });
+  it("DELETE item → delete", () => {
+    expect(classifyEndpoint(ep({ method: "delete", path: "/items/{id}" })).role).toBe("delete");
+  });
+  it("POST on item path → action", () => {
+    expect(classifyEndpoint(ep({ method: "post", path: "/items/{id}/upload" })).role).toBe("action");
+  });
+  it("pet-scoped sub-collection is a list, not a detail", () => {
+    expect(classifyEndpoint(ep({ method: "get", path: "/pets/{id}/photos" })).role).toBe("list");
+  });
+
+  it("non-item PATCH that returns a collection (nestia search) → search/list", () => {
+    // a real PATCH-as-search: array response → a read
+    expect(
+      classifyEndpoint(ep({ method: "patch", path: "/sales", responseBody: { description: "", typeName: "Sale", isArray: true } })).role,
+    ).toBe("list");
+  });
+
+  it("non-item PATCH that returns VOID is a mutation, not a search (safety)", () => {
+    // PATCH /databases/{id}/config returns nothing — a state change, not a read.
+    // Tagging it a read would tell an agent a mutating call is safe.
+    expect(
+      classifyEndpoint(ep({ method: "patch", path: "/databases/{id}/config", responseBody: null })).role,
+    ).toBe("action");
+  });
+
+  it("non-item PATCH returning a single (non-collection) object is a mutation (with document)", () => {
+    // a page wrapper resolves to a collection (read); a plain object does not (write).
+    const doc = {
+      components: { schemas: { Auth: { type: "object", properties: { token: { type: "string" } } } } },
+    } as never;
+    const single = ep({ method: "patch", path: "/authenticate/refresh", responseBody: { description: "", typeName: "Auth", isArray: false } });
+    expect(classifyEndpoint(single, new Set(), doc).role).toBe("action");
+  });
+});
+
+describe("classifyEndpoints — resource grouping", () => {
+  it("buckets by accessor[0] and records the role set", () => {
+    const groups = classifyEndpoints([
+      ep({ method: "get", path: "/pets", accessor: ["pets", "index"] }),
+      ep({ method: "get", path: "/pets/{id}", accessor: ["pets", "at"] }),
+      ep({ method: "post", path: "/pets", accessor: ["pets", "create"] }),
+      ep({ method: "get", path: "/users", accessor: ["users", "index"] }),
+    ]);
+    const pets = groups.find((g) => g.resource === "pets")!;
+    expect(pets.endpoints).toHaveLength(3);
+    expect([...pets.roles].sort()).toEqual(["create", "detail", "list"]);
+    expect(groups.map((g) => g.resource)).toEqual(["pets", "users"]);
+  });
+});

package/src/utils/classifyEndpoints.ts

@@ -0,0 +1,291 @@
+import { OpenApi } from "@typia/interface";
+
+import { extractFields, findCollectionField } from "./extractFields";
+import { IAutoViewEndpoint } from "./toEndpoints";
+
+/**
+ * Deterministic CRUD role of an endpoint — the first brick of the "정확한 틀".
+ *
+ * The MAP layer (SdkStudy + ProductPlan) was 100% LLM improvisation: same
+ * swagger, different screens every run, no CRUD-completeness guarantee, and a
+ * commerce-hardcoded prompt. This classifier derives each endpoint's role from
+ * method + path shape + query presence — purely structural, zero LLM, fully
+ * reproducible and domain-agnostic.
+ *
+ * - `list`    GET on a collection (no trailing path param), no query
+ * - `search`  GET on a collection WITH query parameters (filter/paginate)
+ * - `detail`  GET on a single item (trailing `{param}`)
+ * - `create`  POST on a collection
+ * - `update`  PUT / PATCH on a single item
+ * - `delete`  DELETE on a single item
+ * - `action`  anything else (e.g. POST /pets/{id}/uploadImage, RPC-ish verbs)
+ */
+export type EndpointRole =
+  | "list"
+  | "search"
+  | "detail"
+  | "create"
+  | "update"
+  | "delete"
+  | "action";
+
+/**
+ * One link in a resource hierarchy: a collection name plus the path param that
+ * addresses a single item of it. `param` is `null` for a leaf collection that
+ * the endpoint does not item-address (`/sales/{saleId}/questions` → the
+ * `questions` link has `param: null` on a list, `param: "id"` on a detail).
+ */
+export interface IResourceLink {
+  name: string;
+  param: string | null;
+}
+
+export interface IClassifiedEndpoint {
+  endpoint: IAutoViewEndpoint;
+  /** Top-level resource bucket = the first link of {@link chain}. */
+  resource: string;
+  /**
+   * Full resource hierarchy parsed from the path, skipping namespace/actor
+   * prefixes. `/shoppings/admins/sales/{saleId}/questions/{id}` →
+   * `[{sales, saleId}, {questions, id}]`. Length 1 = a top-level resource.
+   */
+  chain: IResourceLink[];
+  role: EndpointRole;
+  /** True when the path targets a single item (trailing `{param}`). */
+  itemScoped: boolean;
+}
+
+/** All endpoints of one resource, plus the set of roles it actually exposes. */
+export interface IResourceGroup {
+  /** Leaf resource name = the last link of {@link chain}. */
+  resource: string;
+  /** Full hierarchy of this group (`[sales]`, `[sales, questions]`). */
+  chain: IResourceLink[];
+  /** `chain.length` — 1 = top-level, ≥2 = nested under a parent. */
+  depth: number;
+  endpoints: IClassifiedEndpoint[];
+  /** Which CRUD roles this resource supports — drives the screen set later. */
+  roles: Set<EndpointRole>;
+}
+
+const PARAM = /^\{.*\}$/;
+
+function segments(path: string): string[] {
+  return path.split("/").filter((s) => s.length > 0);
+}
+
+/**
+ * Whether an endpoint's response is a browsable collection — an array, or a
+ * page/wrapper object whose resolved fields contain a collection field
+ * (`data` / `items` / `entries` / …). Used to tell a real `PATCH`-as-search
+ * (returns a page of results) from a `PATCH` that merely uses the verb to mutate
+ * a named sub-resource (`/databases/{id}/config`) and returns void or a single
+ * object. Without a document a page wrapper cannot be resolved, so any named
+ * body is conservatively treated as a collection (preserving legacy behavior)
+ * while a void response is still recognized as a non-collection.
+ */
+function returnsCollection(
+  endpoint: IAutoViewEndpoint,
+  document?: OpenApi.IDocument,
+): boolean {
+  if (endpoint.responseBody === null) return false;
+  if (endpoint.responseBody.isArray) return true;
+  if (document === undefined) return true;
+  return (
+    findCollectionField(extractFields(endpoint.responseBody.typeName, document)) !==
+    undefined
+  );
+}
+
+export function classifyEndpoint(
+  endpoint: IAutoViewEndpoint,
+  candidates: ReadonlySet<string> = new Set<string>(),
+  document?: OpenApi.IDocument,
+): IClassifiedEndpoint {
+  const segs = segments(endpoint.path);
+  const last = segs.at(-1) ?? "";
+  // "single item" = the path's last segment is a parameter (`/pets/{id}`),
+  // i.e. it addresses one entity. `/pets/{id}/photos` is a collection again
+  // (last segment `photos` is not a param), so it lists pet-scoped photos.
+  const itemScoped = PARAM.test(last);
+
+  // Any path parameter means the write targets a specific entity (or a child
+  // of one) — `/orders/{id}/cancel`, `/pets/{id}/photos`, `/items/{id}`. We
+  // cannot tell a sub-resource create from an RPC verb deterministically (no
+  // noun/verb NLP), so both collapse to `action`: an item-scoped write the
+  // detail screen surfaces as a button/sub-form. A `create` is reserved for a
+  // POST on a bare collection (`/items`).
+  const hasPathParam = segs.some((s) => PARAM.test(s));
+  const method = endpoint.method.toLowerCase();
+  const hasQuery = endpoint.query !== null;
+
+  const role = ((): EndpointRole => {
+    switch (method) {
+      case "get":
+        // `/pets/{id}` → detail; `/pets/{id}/photos` → list (sub-collection).
+        if (itemScoped) return "detail";
+        return hasQuery ? "search" : "list";
+      case "post":
+        return hasPathParam ? "action" : "create";
+      case "put":
+        return "update";
+      case "patch":
+        // nestia / AutoBE convention: PATCH on a collection is index/search
+        // (the filter rides in the request body), NOT a partial update — this
+        // is how shopping/ERP expose their list endpoints. PATCH on a single
+        // item (`/x/{id}`) is a genuine update.
+        if (itemScoped) return "update";
+        // ...but only when it actually returns a collection. A non-item PATCH
+        // that returns void or a single object (`PATCH /databases/{id}/config`)
+        // is a mutation, not a search — classifying it as a read would tag the
+        // tool `readOnly` and tell an agent a state-changing call is safe.
+        if (!returnsCollection(endpoint, document)) return "action";
+        return hasQuery ? "search" : "list";
+      case "delete":
+        return "delete";
+      default:
+        return "action";
+    }
+  })();
+
+  const chain = resourceChainOf(segs, candidates, role);
+  return {
+    endpoint,
+    resource: chain[0]?.name ?? resourceOf(segs, candidates),
+    chain,
+    role,
+    itemScoped,
+  };
+}
+
+function stripBraces(seg: string): string {
+  return seg.replace(/^\{/, "").replace(/\}$/, "");
+}
+
+/**
+ * Parse a path into its resource hierarchy, skipping namespace / actor prefix
+ * segments. A static segment becomes a resource link when it is item-addressed
+ * (a `{param}` follows it), is a known resource elsewhere (in `candidates`), or
+ * is the terminal collection. Pure namespacing (`shoppings`, `admins`,
+ * `systematic`) is dropped.
+ *
+ * `/shoppings/admins/sales/{saleId}/questions/{id}` → `[{sales,saleId},{questions,id}]`
+ * `/shoppings/customers/orders/{id}/publish` (action) → `[{orders,id}]`
+ *   (the trailing verb is the action name, not a sub-resource).
+ */
+function resourceChainOf(
+  segs: string[],
+  candidates: ReadonlySet<string>,
+  role: EndpointRole,
+): IResourceLink[] {
+  const chain: IResourceLink[] = [];
+  for (let i = 0; i < segs.length; i++) {
+    const seg = segs[i]!;
+    if (PARAM.test(seg)) continue;
+    const next = segs[i + 1];
+    const nextIsParam = next !== undefined && PARAM.test(next);
+    const isTerminal = i === segs.length - 1;
+    if (nextIsParam) {
+      // item-addressed collection → a real resource (`sales/{saleId}`).
+      chain.push({ name: seg, param: stripBraces(next) });
+    } else if (candidates.has(seg)) {
+      // a known resource (item-addressed elsewhere), here without an id.
+      chain.push({ name: seg, param: null });
+    } else if (isTerminal && chain.length === 0) {
+      // a top-level read-only collection that is never item-addressed
+      // (`/health`, `/system`, `/store/inventory`).
+      chain.push({ name: seg, param: null });
+    }
+    // else: a namespace/actor prefix, OR a deeper trailing verb/view that is
+    // never item-addressed (`/sales/details`, `/channels/hierarchical`,
+    // `/orders/incompletes`). The latter is a VARIANT of its parent resource,
+    // not a resource of its own — skip it so the endpoint folds into the parent
+    // group instead of spawning a junk top-level card.
+  }
+  // An action's trailing static verb (`.../{id}/publish`) is not a resource —
+  // drop it so the action attaches to its parent. Keep length ≥ 1.
+  if (role === "action" && chain.length > 1 && chain.at(-1)!.param === null) {
+    chain.pop();
+  }
+  return chain.length > 0 ? chain : [{ name: "root", param: null }];
+}
+
+/**
+ * The segment immediately before a path's last `{param}` — the entity the path
+ * addresses (`/shoppings/admins/coupons/{id}` → `coupons`, `/pet/{petId}` →
+ * `pet`). `null` when the path has no param (a collection or verb path).
+ */
+function paramAnchoredResource(segs: string[]): string | null {
+  for (let i = segs.length - 1; i >= 0; i--) {
+    if (PARAM.test(segs[i]!)) return i > 0 ? segs[i - 1]! : null;
+  }
+  return null;
+}
+
+/**
+ * Resource bucket of a path, using the set of param-anchored resources as
+ * the source of truth.
+ *
+ * - Param path (`/pet/{petId}`, `/coupons/{id}`) → the segment before the
+ *   param. This recovers the real resource even under deep accessors that
+ *   share a `shoppings` prefix.
+ * - Collection / verb path with no param (`/pet/findByStatus`, `/pet`,
+ *   `/user/login`) → absorbed into a known resource if the path passes through
+ *   one (findByStatus → pet, login → user), so RPC-style verbs do not spawn
+ *   junk resources. Falls back to its own last segment when it belongs to no
+ *   known resource (`/store/inventory` → inventory).
+ */
+function resourceOf(segs: string[], candidates: ReadonlySet<string>): string {
+  const anchored = paramAnchoredResource(segs);
+  if (anchored !== null) return anchored;
+  const nonParam = segs.filter((s) => !PARAM.test(s));
+  for (let i = nonParam.length - 1; i >= 0; i--) {
+    if (candidates.has(nonParam[i]!)) return nonParam[i]!;
+  }
+  return nonParam.at(-1) ?? "root";
+}
+
+/**
+ * Classify every endpoint and bucket by resource. Resource order follows first
+ * appearance; endpoints within a resource keep their input order.
+ */
+export function classifyEndpoints(
+  endpoints: IAutoViewEndpoint[],
+  document?: OpenApi.IDocument,
+): IResourceGroup[] {
+  // Pass 1: collect the real resources — segments that have a `{param}` child.
+  const candidates = new Set<string>();
+  for (const endpoint of endpoints) {
+    const r = paramAnchoredResource(segments(endpoint.path));
+    if (r !== null) candidates.add(r);
+  }
+  // Pass 2: classify and bucket by the FULL resource chain (so a sub-resource
+  // like `sales/questions` is its own group, distinct from `sales`), absorbing
+  // param-less verb paths into a known resource.
+  const groups = new Map<string, IResourceGroup>();
+  for (const endpoint of endpoints) {
+    const classified = classifyEndpoint(endpoint, candidates, document);
+    const chainKey = classified.chain.map((c) => c.name).join("/");
+    const existing = groups.get(chainKey);
+    const group: IResourceGroup = existing ?? {
+      resource: classified.chain.at(-1)!.name,
+      chain: classified.chain,
+      depth: classified.chain.length,
+      endpoints: [],
+      roles: new Set<EndpointRole>(),
+    };
+    // Prefer a chain link that carries an item param (a detail endpoint) so the
+    // group's chain has the real param names for routing, not just `null`s.
+    if (existing !== undefined) {
+      classified.chain.forEach((link, i) => {
+        if (link.param !== null && existing.chain[i]?.param == null) {
+          existing.chain[i] = link;
+        }
+      });
+    }
+    group.endpoints.push(classified);
+    group.roles.add(classified.role);
+    groups.set(chainKey, group);
+  }
+  return [...groups.values()];
+}