@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/generator/resources-builder.ts

@@ -13,7 +13,7 @@
 
 import type { EndpointInfo, CrudGroup } from "./types.ts";
 import type { OpenAPIV3 } from "openapi-types";
-import { detectCrudGroups } from "./suite-generator.ts";
+import { detectCrudGroups, singularizeResource, stripTrailingVersionSegments } from "./suite-generator.ts";
 
 export interface ResourceFkRef {
   /** Variable name expected in `.env.yaml` to satisfy the FK (e.g. `audience_id`). */
@@ -78,10 +78,12 @@ export interface IdempotencyConfig {
  * disjointness + has_more consistency.
  *
  * Supported types in this milestone:
- *   • `cursor` — Stripe/GitHub style: caller passes a cursor (e.g.
+ *   • `cursor` — Stripe-style: caller passes a cursor (e.g.
  *     `starting_after=<id>`) derived from the last item of the
- *     previous page. The check is built around this pattern.
- *   • `page` and `offset` — declared for forward compatibility; the
+ *     previous page.
+ *   • `page` — page-number style (GitHub, GitLab, Atlassian, Notion,
+ *     Linear): `?page=N&per_page=M`. ARV-220 enabled this in m-21.
+ *   • `offset` and `token` — declared for forward compatibility; the
  *     check currently skips with a "pagination type not implemented"
  *     reason so the yaml block stays a stable schema.
  *
@@ -178,19 +180,29 @@ export function validateLifecycleManifest(cfg: LifecycleConfig): string[] {
 export interface PaginationConfig {
   /** Pagination flavor. Default `cursor`. */
   type?: "cursor" | "page" | "offset" | "token";
-  /** Query-param name that takes the cursor value. Default `starting_after`. */
+  /** Query-param name that takes the cursor value. Default `starting_after`.
+   *  Only used when `type: cursor`. */
   cursorParam?: string;
-  /** Response field on each item that becomes the next cursor. Default `id`. */
+  /** Response field on each item that becomes the next cursor (cursor-style)
+   *  and the dedupe key when comparing pages (both styles). Default `id`. */
   cursorField?: string;
-  /** Response field that signals "more pages remain". Default `has_more`. */
+  /** Response field that signals "more pages remain". Default `has_more`.
+   *  Only consulted for `type: cursor` — page-style APIs typically rely on
+   *  Link headers or `total_pages` instead, so the field is ignored there. */
   hasMoreField?: string;
-  /** Query-param name for page size. Default `limit`. */
+  /** Query-param name for page size. Default `limit` for cursor-style,
+   *  `per_page` for page-style. */
   limitParam?: string;
   /** Probe page-size. Default 2 (small enough to land two replies fast). */
   defaultLimit?: number;
   /** Response field carrying the array of items. Default `data` (Stripe);
    *  falls back to `items` / `results` when missing. */
   itemsField?: string;
+  /** Page-number query-param name. Default `page`. Only used when `type: page`. */
+  pageParam?: string;
+  /** First page number (1-based on GitHub/GitLab, 0-based on some custom APIs).
+   *  Default 1. Only used when `type: page`. */
+  startPage?: number;
 }
 
 /** ARV-187: LLM-authored example POST body. Stateful checks prefer this
@@ -254,6 +266,135 @@ function isParamSeg(seg: string | undefined): boolean {
   return !!seg && /^\{[^}]+\}$/.test(seg);
 }
 
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * ARV-134 (resource-builder fix #1): when two CRUD groups would collide on
+ * the same `resource` name (e.g. `POST /segments` and `POST /contacts/
+ * {contact_id}/segments` both produce `resource: "segments"`), keep the
+ * canonical (shortest basePath) entry and rename the nested ones to
+ * `<parent-noun>_<resource>` — `contact_segments` here. Without this,
+ * `.api-resources.yaml` ends up with duplicate entries that break
+ * map-by-name lookups (annotate overlay, refresh-api idempotence,
+ * stateful-check resource configs).
+ */
+function disambiguateResourceCollisions(groups: CrudGroup[]): CrudGroup[] {
+  const byName = new Map<string, CrudGroup[]>();
+  for (const g of groups) {
+    const arr = byName.get(g.resource) ?? [];
+    arr.push(g);
+    byName.set(g.resource, arr);
+  }
+
+  const renames = new Map<CrudGroup, string>();
+  const usedNames = new Set<string>(byName.keys());
+
+  for (const [name, members] of byName) {
+    if (members.length < 2) continue;
+    // Canonical name goes to the entry with the *strictly* shortest
+    // basePath (the top-level collection in the typical /segments vs
+    // /contacts/{id}/segments case). If two members tie for shortest,
+    // there is no obvious winner — rename all of them so the yaml never
+    // silently picks one arbitrary entry as canonical.
+    const sorted = [...members].sort((a, b) => a.basePath.length - b.basePath.length);
+    const shortest = sorted[0]!.basePath.length;
+    const tiedAtShortest = sorted.filter(g => g.basePath.length === shortest).length;
+    const startFromIndex = tiedAtShortest === 1 ? 1 : 0;
+
+    for (let i = startFromIndex; i < sorted.length; i++) {
+      const g = sorted[i]!;
+      const prefix = parentNounForBasePath(g.basePath);
+      const singularPrefix = prefix ? singularizeResource(prefix) : null;
+      let candidate = singularPrefix ? `${singularPrefix}_${name}` : `${name}_${i + 1}`;
+      let n = 2;
+      while (usedNames.has(candidate)) {
+        candidate = singularPrefix ? `${singularPrefix}_${name}_${n++}` : `${name}_${n++}`;
+      }
+      usedNames.add(candidate);
+      renames.set(g, candidate);
+    }
+  }
+
+  if (renames.size === 0) return groups;
+  return groups.map(g => (renames.has(g) ? { ...g, resource: renames.get(g)! } : g));
+}
+
+/**
+ * ARV-134 follow-up: same rename strategy as `disambiguateResourceCollisions`,
+ * but operating on the final `ApiResourceEntry[]` so CRUD-vs-implicit
+ * name clashes also get resolved. Keeps the implementation parallel so
+ * the behaviour stays consistent (strictly-shortest basePath keeps the
+ * canonical name; ties get all-renamed; suffix-bumping on hash
+ * collision).
+ */
+function disambiguateEntryCollisions(entries: ApiResourceEntry[]): ApiResourceEntry[] {
+  const byName = new Map<string, ApiResourceEntry[]>();
+  for (const e of entries) {
+    const arr = byName.get(e.resource) ?? [];
+    arr.push(e);
+    byName.set(e.resource, arr);
+  }
+
+  const renames = new Map<ApiResourceEntry, string>();
+  const usedNames = new Set<string>(byName.keys());
+
+  for (const [name, members] of byName) {
+    if (members.length < 2) continue;
+    const sorted = [...members].sort((a, b) => a.basePath.length - b.basePath.length);
+    const shortest = sorted[0]!.basePath.length;
+    const tiedAtShortest = sorted.filter(e => e.basePath.length === shortest).length;
+    const startFromIndex = tiedAtShortest === 1 ? 1 : 0;
+
+    for (let i = startFromIndex; i < sorted.length; i++) {
+      const e = sorted[i]!;
+      const prefix = parentNounForBasePath(e.basePath);
+      const singularPrefix = prefix ? singularizeResource(prefix) : null;
+      let candidate = singularPrefix ? `${singularPrefix}_${name}` : `${name}_${i + 1}`;
+      let n = 2;
+      while (usedNames.has(candidate)) {
+        candidate = singularPrefix ? `${singularPrefix}_${name}_${n++}` : `${name}_${n++}`;
+      }
+      usedNames.add(candidate);
+      renames.set(e, candidate);
+    }
+  }
+
+  if (renames.size === 0) return entries;
+  return entries.map(e => (renames.has(e) ? { ...e, resource: renames.get(e)! } : e));
+}
+
+function parentNounForBasePath(basePath: string): string | null {
+  const segs = pathStripSlash(basePath).split("/").filter(Boolean);
+  // Skip the last segment (the resource itself); walk back to the nearest
+  // non-param noun. `/contacts/{contact_id}/segments` → "contacts".
+  for (let i = segs.length - 2; i >= 0; i--) {
+    if (!isParamSeg(segs[i])) return segs[i]!;
+  }
+  return null;
+}
+
+/**
+ * ARV-134 (resource-builder fix #2): for an implicit list-only resource
+ * (no CRUD group), look for a GET-by-id companion endpoint that gives us
+ * a real idParam + itemPath. Resend's `/logs/{log_id}` and `/automations/
+ * {automation_id}/runs/{run_id}` were getting `idParam: ""` because the
+ * implicit-resource constructor never inspected the spec for their item
+ * endpoints — `prepare-fixtures` then skipped them.
+ */
+function findItemEndpointForListPath(
+  listPath: string,
+  endpoints: EndpointInfo[],
+): EndpointInfo | null {
+  const itemRe = new RegExp(`^${escapeRegex(listPath)}/\\{([^}]+)\\}/?$`);
+  for (const ep of endpoints) {
+    if (ep.method.toUpperCase() !== "GET" || ep.deprecated) continue;
+    if (itemRe.test(pathStripSlash(ep.path))) return ep;
+  }
+  return null;
+}
+
 function getCaptureField(create: EndpointInfo): string {
   // Look at the create endpoint's success response schema for an `id`-ish
   // field. Falls back to "id" — the universal default.
@@ -283,9 +424,24 @@ function getCaptureField(create: EndpointInfo): string {
  *    we walk back to the nearest non-param segment and search for any
  *    GET path ending with that hint).
  */
+// ARV-376: list-shaped verb suffixes. `/api/business-segment20/list` is the
+// collection listing for stem `/api/business-segment20`, even though the
+// stem itself is not a GET endpoint. Same for `/search` and `/find`.
+const LIST_VERB_SUFFIXES = new Set(["list", "search", "find"]);
+
 export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, string> {
   const getPathSet = new Set<string>();
   const getPathsByLastSeg = new Map<string, string[]>();
+  // ARV-376: a `/list`-style endpoint indexed by its collection stem
+  // (path minus the verb suffix) and by that stem's last noun segment, so a
+  // read-by-id sibling (`/{code}`, `/byid/{id}`) can find its listing even
+  // though the bare collection path has no GET.
+  const listByStem = new Map<string, string>();
+  const listByStemLastSeg = new Map<string, string[]>();
+  const considerShortest = (map: Map<string, string>, key: string, path: string) => {
+    const cur = map.get(key);
+    if (!cur || path.length < cur.length) map.set(key, path);
+  };
   for (const ep of endpoints) {
     if (ep.method.toUpperCase() !== "GET" || ep.deprecated) continue;
     const path = pathStripSlash(ep.path);
@@ -297,6 +453,20 @@ export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, st
       arr.push(path);
       getPathsByLastSeg.set(last, arr);
     }
+    // Index list-verb endpoints against their collection stem. The stem key
+    // is the leading-slash path form the resolution loop below builds its
+    // prefixes in (NOT the filtered form) so the two sides compare equal.
+    if (last && LIST_VERB_SUFFIXES.has(last.toLowerCase()) && segs.length >= 2) {
+      const stemLast = segs[segs.length - 2];
+      if (stemLast && !isParamSeg(stemLast)) {
+        const lastSlash = path.lastIndexOf("/");
+        const stemPath = lastSlash > 0 ? path.slice(0, lastSlash) : "";
+        considerShortest(listByStem, stemPath, path);
+        const arr = listByStemLastSeg.get(stemLast) ?? [];
+        arr.push(path);
+        listByStemLastSeg.set(stemLast, arr);
+      }
+    }
   }
 
   const result = new Map<string, string>();
@@ -314,21 +484,27 @@ export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, st
       const m = /^\{([^}]+)\}$/.exec(seg);
       if (!m) continue;
       const param = m[1]!;
-      const prevSeg = segs[i - 1];
-
-      // Strategy 1 (canonical): prev seg is a non-param noun and the
-      // prefix up to (but not including) `{param}` is a GET endpoint.
-      if (prevSeg && !isParamSeg(prevSeg)) {
-        const prefix = segs.slice(0, i).join("/");
-        if (getPathSet.has(prefix)) {
-          consider(param, prefix);
-          continue;
-        }
+
+      // Strategy 1 (canonical + ARV-376): walk back over the run of
+      // consecutive non-param segments before `{param}`; for each candidate
+      // prefix match either a collection GET or a `/list`-style endpoint.
+      // Longest (most specific) prefix wins. Stops at the first param
+      // segment so we never attribute a child id to a grandparent list. This
+      // tolerates read-by-id marker segments (`/byid/{id}` → owner is the
+      // `/business-segment20/list` two segments up).
+      let matched = false;
+      for (let k = i; k >= 1; k--) {
+        if (isParamSeg(segs[k - 1]!)) break; // hit a param boundary — stop
+        const prefix = segs.slice(0, k).join("/");
+        if (getPathSet.has(prefix)) { consider(param, prefix); matched = true; break; }
+        const listPath = listByStem.get(prefix);
+        if (listPath) { consider(param, listPath); matched = true; break; }
       }
+      if (matched) continue;
 
       // Strategy 2 (sibling-param chain): walk back to the nearest
       // non-param segment, then look for *any* GET path that terminates
-      // with that segment. Pick the shortest match.
+      // with that segment (or a `/list`-style endpoint for that stem).
       let hint: string | undefined;
       for (let j = i - 1; j >= 0; j--) {
         const s = segs[j]!;
@@ -338,7 +514,7 @@ export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, st
         }
       }
       if (!hint) continue;
-      const candidates = getPathsByLastSeg.get(hint);
+      const candidates = getPathsByLastSeg.get(hint) ?? listByStemLastSeg.get(hint);
       if (!candidates || candidates.length === 0) continue;
       const shortest = candidates.reduce((a, b) => (a.length <= b.length ? a : b));
       consider(param, shortest);
@@ -349,7 +525,11 @@ export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, st
 }
 
 function listPathToResourceName(listPath: string): string {
-  const segs = pathStripSlash(listPath).split("/").filter(Boolean);
+  // ARV-372/ARV-369 follow-up: strip trailing version segments (`v30`)
+  // before scanning backward, same as the CRUD-group resource-name
+  // derivation in suite-generator.ts — otherwise list-only resources on a
+  // spec shaped `/api/<resource>/v{N}` all collapse to "v30".
+  const segs = stripTrailingVersionSegments(pathStripSlash(listPath).split("/").filter(Boolean));
   for (let i = segs.length - 1; i >= 0; i--) {
     if (!isParamSeg(segs[i])) return segs[i]!;
   }
@@ -430,9 +610,18 @@ export interface BuildResourcesParams {
 }
 
 export function buildApiResourceMap(params: BuildResourcesParams): ApiResourceMap {
-  const groups = detectCrudGroups(params.endpoints);
+  const groups = disambiguateResourceCollisions(detectCrudGroups(params.endpoints));
   const ownerListPaths = resolveOwnerListPaths(params.endpoints);
 
+  // ARV-134: reverse-index ownerListPaths so implicit resources can fall
+  // back to the FK param name when no direct GET-by-id companion exists.
+  const paramsByListPath = new Map<string, string[]>();
+  for (const [param, listPath] of ownerListPaths) {
+    const arr = paramsByListPath.get(listPath) ?? [];
+    arr.push(param);
+    paramsByListPath.set(listPath, arr);
+  }
+
   // Index CRUD-group list paths by normalised path so the FK resolver can
   // hand back the resource name a structural lookup pointed at.
   const resourceByListPath = new Map<string, string>();
@@ -460,14 +649,45 @@ export function buildApiResourceMap(params: BuildResourcesParams): ApiResourceMa
     );
     if (!listEp) continue;
     const name = listPathToResourceName(listPath);
+
+    // ARV-134: try to recover idParam + itemPath from a GET-by-id companion
+    // (e.g. implicit `logs` at `/logs` + `GET /logs/{log_id}` → log_id).
+    // Falls back to the reverse-indexed ownerListPaths param when no direct
+    // item endpoint exists — preferring a name that matches the resource's
+    // singular form so e.g. `attachment_id` wins over a sibling FK that
+    // happens to point at the same list path.
+    const itemEp = findItemEndpointForListPath(listPath, params.endpoints);
+    let idParam = "";
+    let itemPath = "";
+    const endpoints: ApiResourceEntry["endpoints"] = { list: epLabel(listEp) };
+    if (itemEp) {
+      const m = pathStripSlash(itemEp.path).match(/\{([^}]+)\}\/?$/);
+      if (m) {
+        idParam = m[1]!;
+        itemPath = itemEp.path;
+        endpoints.read = epLabel(itemEp);
+      }
+    }
+    if (!idParam) {
+      const candidates = paramsByListPath.get(listPath) ?? [];
+      if (candidates.length > 0) {
+        const singular = singularizeResource(name).toLowerCase();
+        const preferred = candidates.find(p => {
+          const lower = p.toLowerCase();
+          return lower === singular || lower.startsWith(`${singular}_`);
+        });
+        idParam = preferred ?? candidates[0]!;
+      }
+    }
+
     implicitResources.push({
       resource: name,
       basePath: listPath,
-      itemPath: "",
-      idParam: "",
+      itemPath,
+      idParam,
       captureField: "id",
       hasFullCrud: false,
-      endpoints: { list: epLabel(listEp) },
+      endpoints,
       fkDependencies: [],
     });
     resourceByListPath.set(listPath, name);
@@ -510,7 +730,35 @@ export function buildApiResourceMap(params: BuildResourcesParams): ApiResourceMa
     r.fkDependencies = collectPathFkDeps(r.basePath, "", ownerListPaths, resourceByListPath);
   }
 
-  const resources = [...crudResources, ...implicitResources];
+
+  // ARV-134 (follow-up): the early disambiguation pass only operated on
+  // CRUD groups, but collisions also fire CRUD-vs-implicit (`/repos/
+  // {owner}/{repo}/check-runs` is CRUD, `/repos/{owner}/{repo}/commits/
+  // {ref}/check-runs` is implicit-list-only — both end up named
+  // `check-runs`). Run the same prefix-rename here on the combined list
+  // so the final yaml never carries duplicate `resource:` lines.
+  const resources = disambiguateEntryCollisions([...crudResources, ...implicitResources]);
+
+  // ARV-376: surface a resource's OWN secondary lookup keys (e.g. the
+  // `/{code}` read-by-code param, or a `/byid/{id}` param that isn't the
+  // canonical idParam) as fillable targets. resolveOwnerListPaths already
+  // links each such param to this resource's `/list` endpoint; expose it as a
+  // self-referential fkDependency so prepare-fixtures reports a candidate
+  // (GET the list, pick a value) instead of `miss-no-list`. Runs after
+  // disambiguateEntryCollisions so it keys off the FINAL unique resource
+  // names (pre-disambig implicit names collide on `list`).
+  const byOwnListPath = new Map<string, ApiResourceEntry>();
+  for (const r of resources) {
+    const label = r.endpoints.list;
+    if (!label) continue;
+    byOwnListPath.set(pathStripSlash(label.slice(label.indexOf(" ") + 1)), r);
+  }
+  for (const [param, listPath] of ownerListPaths) {
+    const r = byOwnListPath.get(pathStripSlash(listPath));
+    if (!r || param === r.idParam) continue;
+    if ((r.fkDependencies ?? []).some(d => d.var === param)) continue;
+    r.fkDependencies.push({ var: param, param, in: "path", ownerResource: r.resource });
+  }
 
   // Endpoints that aren't in any CRUD group — RPC-style actions, webhook
   // accept-only routes, etc. Implicit-list endpoints stay in orphans
@@ -614,6 +862,8 @@ export function serializeApiResourceMap(m: ApiResourceMap): string {
       if (r.pagination.limitParam) lines.push(`      limit_param: ${escape(r.pagination.limitParam)}`);
       if (r.pagination.defaultLimit != null) lines.push(`      default_limit: ${r.pagination.defaultLimit}`);
       if (r.pagination.itemsField) lines.push(`      items_field: ${escape(r.pagination.itemsField)}`);
+      if (r.pagination.pageParam) lines.push(`      page_param: ${escape(r.pagination.pageParam)}`);
+      if (r.pagination.startPage != null) lines.push(`      start_page: ${r.pagination.startPage}`);
     }
     if (r.lifecycle) {
       lines.push(`    lifecycle:`);

package/src/core/generator/schema-utils.ts

@@ -4,6 +4,16 @@ import type { OpenAPIV3 } from "openapi-types";
  * Deep-clone an object, replacing circular references with the vendor-extension
  * sentinel `{ "x-circular": true }`. Uses WeakSet to track visited objects.
  *
+ * Trade-off (intentional): we mark the SECOND visit of any shared object
+ * (post-`dereference()` $ref-target reused under multiple parents) as
+ * circular, not just true cycles. The alternative — a DFS path stack —
+ * preserves every duplicate fresh, but blows the GitHub spec from 14 MB
+ * to 106 MB on disk because shared `per_page`/`page`/`owner` params and
+ * response schemas are re-cloned for every endpoint that references them.
+ * Downstream tools that need param/schema visibility on every endpoint
+ * (e.g. `zond api annotate auto`, ARV-262) handle this by re-reading the
+ * source spec themselves rather than relying on `apis/<name>/spec.json`.
+ *
  * Why a vendor extension and not `$ref`: the decycled doc is now written to
  * disk (apis/<name>/spec.json) and re-read by `@readme/openapi-parser` in
  * downstream commands (check spec, describe, generate). If the sentinel
@@ -24,6 +34,18 @@ export function decycleSchema(obj: unknown): unknown {
 
     const obj = value as Record<string, unknown>;
     if (seen.has(obj)) {
+      // ARV-262: parameter-shaped objects (have both `name` and `in`)
+      // appear post-`dereference()` as shared identities across every
+      // endpoint that $ref'd them — `per_page`, `page`, `owner`, etc.
+      // Past the first visit, the full `{"x-circular": true}` stub
+      // erases name+in and downstream tools (annotate auto, generator)
+      // can no longer tell what query/header that slot represented.
+      // Preserve name+in on revisit; schema/required/description still
+      // collapse so the bulk-size trade-off is unchanged (revisits
+      // grow by ~30 B each, vs. ~7×-blowup if we cloned everything).
+      if (typeof obj.name === "string" && typeof obj.in === "string") {
+        return { name: obj.name, in: obj.in };
+      }
       return { "x-circular": true };
     }
     seen.add(obj);