@kirrosh/zond 0.21.0 → 0.23.0

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

@@ -0,0 +1,325 @@
+/**
+ * Build `.api-fixtures.yaml` — manifest of variables this API needs from
+ * the user's `.env.yaml`.
+ *
+ * Purpose: when the skill (or `zond doctor`, future) needs to tell the
+ * user what to fill in before scenarios will run, it reads this manifest
+ * instead of inferring fixtures from generated tests. The manifest is
+ * derived purely from the OpenAPI spec — auth schemes, required path
+ * params, server URL — so it's stable across re-runs of `generate`.
+ *
+ * Manifest is read-only (regenerate via `zond refresh-api`); user edits
+ * land in `.env.yaml`, not here.
+ */
+
+import type { EndpointInfo, SecuritySchemeInfo } from "./types.ts";
+import { schemeVarName, resourceVar } from "./suite-generator.ts";
+import type { ApiResourceMap } from "./resources-builder.ts";
+
+/**
+ * ARV-138: canonicalise a body field name to a manifest var name.
+ * Converts camelCase → snake_case + lowercase so spec body fields
+ * (`issueId`, `audienceId`, `accountID`) collapse onto the same manifest
+ * entry as the spec's path-param spelling (`issue_id`, `audience_id`).
+ *
+ * Idempotent on already-snake_case input. The HTTP request still sends
+ * the raw field name to the server — only the var-name namespace is
+ * normalised (see `create-body.ts:substituteFkFields`).
+ */
+export function canonicalVarName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .toLowerCase();
+}
+
+export type FixtureSource = "auth" | "server" | "path" | "header" | "body-fk" | "capture-chain";
+
+export interface FixtureRequirement {
+  /** Variable name as referenced via {{var}} in tests. */
+  name: string;
+  /** Where this fixture comes from in the spec. */
+  source: FixtureSource;
+  /** Free-text description for the user (one line). */
+  description: string;
+  /** Endpoints affected if this fixture is missing (sample, ≤10). */
+  affectedEndpoints: string[];
+  /** True when at least one consumer marks this required. */
+  required: boolean;
+  /** Suggested placeholder value, used to seed `.env.yaml`. */
+  defaultValue?: string;
+}
+
+export interface ApiFixtureManifest {
+  generatedAt: string;
+  specHash: string;
+  fixtureCount: number;
+  fixtures: FixtureRequirement[];
+}
+
+function epLabel(ep: EndpointInfo): string {
+  return `${ep.method.toUpperCase()} ${ep.path}`;
+}
+
+function pushAffected(req: FixtureRequirement, ep: EndpointInfo): void {
+  if (req.affectedEndpoints.length >= 10) return;
+  const label = epLabel(ep);
+  if (!req.affectedEndpoints.includes(label)) req.affectedEndpoints.push(label);
+}
+
+export interface BuildFixturesParams {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+  baseUrl?: string;
+  specHash: string;
+  /**
+   * Resource map (CRUD groups + body-FK refs) — when provided, the manifest
+   * also lists body-FK and capture-chain variables that the test generator
+   * will reference. Keeps `.api-fixtures.yaml` in sync with what generated
+   * tests actually consume (per decision-7: manifest = source of truth for
+   * the *list* of variables).
+   */
+  resourceMap?: ApiResourceMap;
+}
+
+export function buildApiFixtureManifest(params: BuildFixturesParams): ApiFixtureManifest {
+  const fixtures = new Map<string, FixtureRequirement>();
+
+  // 1. Server URL → base_url
+  fixtures.set("base_url", {
+    name: "base_url",
+    source: "server",
+    description: params.baseUrl
+      ? `Base URL of the API (from spec: ${params.baseUrl}).`
+      : `Base URL of the API. Spec did not declare a server — fill in manually.`,
+    affectedEndpoints: ["*"],
+    required: true,
+    defaultValue: params.baseUrl ?? "",
+  });
+
+  // 2. Auth schemes → auth tokens
+  // We map each scheme that endpoints actually reference into an env var.
+  const usedSchemeNames = new Set<string>();
+  for (const ep of params.endpoints) {
+    for (const s of ep.security) usedSchemeNames.add(s);
+  }
+  for (const scheme of params.securitySchemes) {
+    if (!usedSchemeNames.has(scheme.name)) continue;
+    const varName = schemeVarName(scheme, params.securitySchemes);
+    let description: string;
+    if (scheme.type === "http" && scheme.scheme === "bearer") {
+      description = `Bearer token for security scheme "${scheme.name}".`;
+    } else if (scheme.type === "apiKey") {
+      description = `API key for "${scheme.name}" (sent as ${scheme.in === "header" ? `header ${scheme.apiKeyName}` : `${scheme.in} param ${scheme.apiKeyName}`}).`;
+    } else if (scheme.type === "oauth2") {
+      description = `OAuth2 access token for scheme "${scheme.name}".`;
+    } else {
+      description = `Token for security scheme "${scheme.name}" (${scheme.type}).`;
+    }
+    const existing = fixtures.get(varName);
+    if (existing) {
+      // Multiple schemes might collapse to one var (single-bearer case).
+      // Keep the most informative description.
+      if (description.length > existing.description.length) existing.description = description;
+    } else {
+      fixtures.set(varName, {
+        name: varName,
+        source: "auth",
+        description,
+        affectedEndpoints: [],
+        required: true,
+        defaultValue: "",
+      });
+    }
+    const req = fixtures.get(varName)!;
+    for (const ep of params.endpoints) {
+      if (ep.security.includes(scheme.name)) pushAffected(req, ep);
+    }
+  }
+
+  // 3. Required path params → one var per unique name
+  for (const ep of params.endpoints) {
+    for (const p of ep.parameters) {
+      if (p.in !== "path") continue;
+      if (p.required === false) continue;
+      const name = p.name;
+      let req = fixtures.get(name);
+      if (!req) {
+        const schema = p.schema as { type?: string; format?: string; example?: unknown } | undefined;
+        let defaultValue = "";
+        if (schema?.example !== undefined) defaultValue = String(schema.example);
+        else if (schema?.format === "uuid") defaultValue = "";
+        else if (schema?.type === "integer" || schema?.type === "number") defaultValue = "";
+
+        req = {
+          name,
+          source: "path",
+          description: `Path parameter ${name}${schema?.format ? ` (${schema.format})` : schema?.type ? ` (${schema.type})` : ""}. Set to a real id from your account, or leave blank to skip dependent tests.`,
+          affectedEndpoints: [],
+          required: true,
+          defaultValue,
+        };
+        fixtures.set(name, req);
+      }
+      pushAffected(req, ep);
+    }
+  }
+
+  // 4. Required header params → one var per unique name (skip Authorization
+  //    & Content-Type — those are handled by auth + suite headers).
+  for (const ep of params.endpoints) {
+    for (const p of ep.parameters) {
+      if (p.in !== "header") continue;
+      if (p.required === false) continue;
+      const lname = p.name.toLowerCase();
+      if (lname === "authorization" || lname === "content-type" || lname === "accept") continue;
+      const varName = lname.replace(/-/g, "_");
+      let req = fixtures.get(varName);
+      if (!req) {
+        req = {
+          name: varName,
+          source: "header",
+          description: `Required header ${p.name}.`,
+          affectedEndpoints: [],
+          required: true,
+          defaultValue: "",
+        };
+        fixtures.set(varName, req);
+      }
+      pushAffected(req, ep);
+    }
+  }
+
+  // 5. Body-FK fields — required parent-id fields in request bodies that
+  //    the generator copies from `.env.yaml` (e.g. `audience_id` in
+  //    POST /contacts). Without these in the manifest, prepare-fixtures
+  //    discovers/seeds nothing for them and `zond audit` 422s on first
+  //    nested resource. Walks ALL mutating endpoints (not only full
+  //    CRUD groups) so POST-only resources still surface their FK deps.
+  //    Source precedence: path > body-fk (path-params more constraining).
+  for (const ep of params.endpoints) {
+    const method = ep.method.toUpperCase();
+    if (method !== "POST" && method !== "PUT" && method !== "PATCH") continue;
+    const schema = ep.requestBodySchema as
+      | { properties?: Record<string, unknown>; required?: string[] }
+      | undefined;
+    if (!schema?.properties) continue;
+    const required = new Set(schema.required ?? []);
+    for (const fieldName of Object.keys(schema.properties)) {
+      if (!/_id$|Id$|_uuid$/.test(fieldName)) continue;
+      if (!required.has(fieldName)) continue;
+      // ARV-138: canonicalise camelCase to snake_case so `issueId` shares
+      // a manifest slot with path-param `issue_id`. The raw `fieldName`
+      // still goes to the server unchanged via `create-body.ts` —
+      // canonicalisation only affects the manifest var-name namespace.
+      const varName = canonicalVarName(fieldName);
+      const existing = fixtures.get(varName);
+      if (existing) {
+        // Already covered (likely as path-param). Keep the existing entry
+        // and just surface the additional affected endpoint.
+        pushAffected(existing, ep);
+        continue;
+      }
+      fixtures.set(varName, {
+        name: varName,
+        source: "body-fk",
+        description: `Foreign-key id consumed by ${epLabel(ep)} request body. Set to a real id from your account, or leave blank to skip dependent tests.`,
+        affectedEndpoints: [epLabel(ep)],
+        required: true,
+        defaultValue: "",
+      });
+    }
+  }
+
+  // 6. CRUD-chain capture vars — the generator emits `capture: <idParam>`
+  //    in POST steps and references {{<idParam>}} downstream. These are
+  //    auto-captured at runtime; surfacing them in the manifest keeps the
+  //    "var in tests but not in manifest" contract intact (per decision-7)
+  //    and lets prepare-fixtures distinguish "captured automatically" from
+  //    "user must fill". required: false — env override is advanced-only.
+  //
+  //    ARV-137: capture name = `r.idParam` (the spec's path-param name), not
+  //    `resourceVar(r.resource, "id")`. The synthesised form produced phantom
+  //    manifest dupes whenever the spec's path-param didn't equal
+  //    `<resource>_id` (e.g. monitors/monitor_id_or_slug, saved/query_id,
+  //    releases/version). Now the manifest carries one var per resource id
+  //    that matches both the path-source entry and the generated test refs.
+  if (params.resourceMap) {
+    for (const r of params.resourceMap.resources) {
+      if (!r.endpoints.create) continue;
+      const captureName = r.idParam || resourceVar(r.resource, "id");
+      if (fixtures.has(captureName)) continue;
+      const description = `Captured automatically from ${r.endpoints.create} response (field "${r.captureField}") and used in downstream CRUD steps. Set in .env.yaml only to override the captured value.`;
+      const affectedFromGroup = Object.entries(r.endpoints)
+        .filter(([k]) => k !== "list" && k !== "create")
+        .map(([, v]) => v as string);
+      const req: FixtureRequirement = {
+        name: captureName,
+        source: "capture-chain",
+        description,
+        affectedEndpoints: affectedFromGroup.slice(0, 10),
+        required: false,
+        defaultValue: "",
+      };
+      fixtures.set(captureName, req);
+    }
+  }
+
+  const ordered = Array.from(fixtures.values()).sort((a, b) => {
+    const sourceOrder: Record<FixtureSource, number> = {
+      server: 0,
+      auth: 1,
+      header: 2,
+      path: 3,
+      "body-fk": 4,
+      "capture-chain": 5,
+    };
+    if (sourceOrder[a.source] !== sourceOrder[b.source]) {
+      return sourceOrder[a.source] - sourceOrder[b.source];
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  return {
+    generatedAt: new Date().toISOString(),
+    specHash: params.specHash,
+    fixtureCount: ordered.length,
+    fixtures: ordered,
+  };
+}
+
+// ── YAML serialization ──
+
+function escape(s: string): string {
+  if (/[:#\[\]{}&*!|>'"@`,%]/.test(s) || s.includes("\n") || s === "") {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+export function serializeApiFixtureManifest(m: ApiFixtureManifest): string {
+  const lines: string[] = [];
+  lines.push("# Auto-generated by zond. Do not edit by hand.");
+  lines.push("# Read-only manifest of variables this API needs in .env.yaml.");
+  lines.push("# Regenerate via: zond refresh-api <name>");
+  lines.push(`generatedAt: ${escape(m.generatedAt)}`);
+  lines.push(`specHash: ${escape(m.specHash)}`);
+  lines.push(`fixtureCount: ${m.fixtureCount}`);
+  lines.push("fixtures:");
+  for (const f of m.fixtures) {
+    lines.push(`  - name: ${escape(f.name)}`);
+    lines.push(`    source: ${f.source}`);
+    lines.push(`    required: ${f.required}`);
+    lines.push(`    description: ${escape(f.description)}`);
+    if (f.defaultValue !== undefined) {
+      lines.push(`    defaultValue: ${escape(f.defaultValue)}`);
+    }
+    if (f.affectedEndpoints.length === 0) {
+      lines.push(`    affectedEndpoints: []`);
+    } else {
+      lines.push(`    affectedEndpoints:`);
+      for (const e of f.affectedEndpoints) lines.push(`      - ${escape(e)}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}

package/src/core/generator/index.ts

@@ -1,14 +1,16 @@
 export { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "./openapi-reader.ts";
-export { serializeSuite, isRelativeUrl, sanitizeEnvName, resolveSpecPath } from "./serializer.ts";
+export { serializeSuite } from "./serializer.ts";
 export type { RawSuite, RawStep } from "./serializer.ts";
-export { generateFromSchema } from "./data-factory.ts";
 export { scanCoveredEndpoints, filterUncoveredEndpoints, normalizePath, specPathToRegex } from "./coverage-scanner.ts";
 export type { CoveredEndpoint } from "./coverage-scanner.ts";
 export { analyzeEndpoints } from "./endpoint-warnings.ts";
-export { compressEndpointsWithSchemas, buildGenerationGuide } from "./guide-builder.ts";
-export type { GuideOptions } from "./guide-builder.ts";
 export type { EndpointWarning, WarningCode } from "./endpoint-warnings.ts";
 export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.ts";
-export { generateSuites, generateStep, detectCrudGroups, generateCrudSuite, generateSanitySuite, findUnresolvedVars } from "./suite-generator.ts";
 export { buildCatalog, serializeCatalog } from "./catalog-builder.ts";
 export type { ApiCatalog, CatalogEndpoint } from "./catalog-builder.ts";
+export { buildApiResourceMap, serializeApiResourceMap } from "./resources-builder.ts";
+export type { ApiResourceMap, ApiResourceEntry, ResourceFkRef } from "./resources-builder.ts";
+export { buildApiFixtureManifest, serializeApiFixtureManifest } from "./fixtures-builder.ts";
+export type { ApiFixtureManifest, FixtureRequirement, FixtureSource } from "./fixtures-builder.ts";
+export { buildCreateRequestBody } from "./create-body.ts";
+export type { BuildCreateRequestBodyOptions } from "./create-body.ts";

package/src/core/generator/openapi-reader.ts

@@ -1,6 +1,7 @@
 import { dereference } from "@readme/openapi-parser";
 import type { OpenAPIV3 } from "openapi-types";
 import type { EndpointInfo, ResponseInfo, SecuritySchemeInfo } from "./types.ts";
+import { disambiguateGenericPathParams } from "./path-param-disambig.ts";
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
 
@@ -57,9 +58,16 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
 
       const parameters: OpenAPIV3.ParameterObject[] = [];
 
+      // Skip circular-ref sentinel stubs emitted by decycleSchema —
+      // they look like `{ "x-circular": true }` (no .name, no .in) and
+      // crash downstream code that expects p.name/p.in. ARV-200 (R10/F1).
+      const isUsableParam = (p: any): p is OpenAPIV3.ParameterObject =>
+        p != null && typeof p === "object" && typeof p.name === "string" && typeof p.in === "string";
+
       // Path-level parameters
       if (pathItem.parameters) {
         for (const p of pathItem.parameters) {
+          if (!isUsableParam(p)) continue;
           parameters.push(p as OpenAPIV3.ParameterObject);
         }
       }
@@ -67,6 +75,7 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
       // Operation-level parameters (override path-level)
       if (operation.parameters) {
         for (const p of operation.parameters) {
+          if (!isUsableParam(p)) continue;
           const param = p as OpenAPIV3.ParameterObject;
           const existingIdx = parameters.findIndex(
             (existing) => existing.name === param.name && existing.in === param.in,
@@ -93,6 +102,24 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
           const chosen = rb.content[requestBodyContentType!];
           if (chosen?.schema) {
             requestBodySchema = chosen.schema as OpenAPIV3.SchemaObject;
+            // OpenAPI allows examples at the media-type level (sibling to schema).
+            // Lift them onto the schema so the generator sees a single signal.
+            if (requestBodySchema.example === undefined) {
+              if ((chosen as OpenAPIV3.MediaTypeObject).example !== undefined) {
+                requestBodySchema = {
+                  ...requestBodySchema,
+                  example: (chosen as OpenAPIV3.MediaTypeObject).example,
+                };
+              } else if (chosen.examples) {
+                const firstNamed = Object.values(chosen.examples)[0];
+                if (firstNamed && typeof firstNamed === "object" && "value" in firstNamed) {
+                  requestBodySchema = {
+                    ...requestBodySchema,
+                    example: (firstNamed as OpenAPIV3.ExampleObject).value,
+                  };
+                }
+              }
+            }
           }
         }
       }
@@ -102,9 +129,12 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
       const responseContentTypesSet = new Set<string>();
       if (operation.responses) {
         for (const [statusCode, responseObj] of Object.entries(operation.responses)) {
+          const parsedStatus = parseInt(statusCode, 10);
+          // Skip non-numeric keys like "default" — they have no asserting status code.
+          if (!Number.isFinite(parsedStatus)) continue;
           const resp = responseObj as OpenAPIV3.ResponseObject;
           const info: ResponseInfo = {
-            statusCode: parseInt(statusCode, 10),
+            statusCode: parsedStatus,
             description: resp.description || "",
           };
           if (resp.content) {
@@ -141,11 +171,33 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
         responseContentTypes: [...responseContentTypesSet],
         responses,
         security,
-        deprecated: operation.deprecated ?? false,
+        deprecated: (operation.deprecated ?? false) || isMarkedDeprecatedInText(operation.summary, operation.description, operation.operationId),
         requiresEtag,
       });
     }
   }
 
-  return endpoints;
+  // ARV-40: when generic path-param names (`{id}`, `{slug}`, ...) collide
+  // across multiple resources, rewrite each to `<parent_singular>_<param>`
+  // so the manifest derives per-resource vars and tests stop sharing one
+  // global `id`. In-memory only; on-disk spec stays untouched.
+  return disambiguateGenericPathParams(endpoints);
+}
+
+/** Spec authors often mark endpoints as deprecated in the summary or
+ *  description text instead of (or in addition to) the `deprecated: true`
+ *  flag — common across many SaaS and legacy specs. Without this
+ *  fallback, generator emits CRUD suites whose POST returns 404 from a dead
+ *  endpoint. (TASK-245) */
+/** Matches `(DEPRECATED) ...`, `[DEPRECATED] ...`, `DEPRECATED: ...` at the
+ *  start of a string. Also matches markdown `## Deprecated` headings, which
+ *  some spec authors use in operation `description` to flag end-of-life
+ *  endpoints. */
+const DEPRECATED_PREFIX_RE = /^\s*[\(\[]?\s*DEPRECATED\s*[\)\]:\-—\s]/i;
+const DEPRECATED_HEADING_RE = /^\s*#+\s*Deprecated\b/im;
+function isMarkedDeprecatedInText(summary?: string, description?: string, operationId?: string): boolean {
+  if (summary && DEPRECATED_PREFIX_RE.test(summary)) return true;
+  if (operationId && DEPRECATED_PREFIX_RE.test(operationId)) return true;
+  if (description && (DEPRECATED_PREFIX_RE.test(description) || DEPRECATED_HEADING_RE.test(description))) return true;
+  return false;
 }

package/src/core/generator/path-param-disambig.ts

@@ -0,0 +1,114 @@
+/**
+ * Disambiguate generic path-parameter names that collide across resources.
+ *
+ * Some OpenAPI specs declare item paths as `/<resource>/{id}` instead of
+ * `/<resource>/{<resource>_id}` — fine
+ * within one resource, catastrophic across many: the manifest derives one
+ * global `id` var, `.env.yaml` stores one value, and N>1 CRUD suites end up
+ * pointing at the same uuid (false 404 at best; false 200 against a stranger's
+ * object at worst — the GET returns a real object so the test "passes" while
+ * having tested nothing of the target resource).
+ *
+ * ARV-40 fix: when a generic param name (`id`, `slug`, `uuid`, `key`,
+ * `identifier`) appears under more than one distinct parent collection in the
+ * spec, rewrite each occurrence to `<parent_singular>_<param>` in
+ * EndpointInfo.path AND the matching parameter entry. All downstream code
+ * (resource map, fixture manifest, suite generator, mass-assignment probe)
+ * then sees per-resource var names without any extra plumbing.
+ *
+ * The on-disk OpenAPI spec.json is untouched — this is an in-memory
+ * normalisation. Coverage matches by structural shape (`{x}` is `{x}`), and
+ * the runner substitutes `{{var}}` after path templating, so renaming
+ * `{id}` → `{template_id}` only affects how zond *names* the variable.
+ */
+
+import type { EndpointInfo } from "./types.ts";
+
+const GENERIC_PARAM_NAMES = new Set(["id", "slug", "uuid", "key", "name", "identifier"]);
+
+function isParamSeg(seg: string | undefined): seg is string {
+  return !!seg && /^\{[^}]+\}$/.test(seg);
+}
+
+/** English singularization sufficient for resource-collection nouns. */
+function singularize(word: string): string {
+  if (word.length > 3 && /ies$/i.test(word)) return word.slice(0, -3) + "y";
+  if (word.length > 3 && /(ch|sh|x|ss|z)es$/i.test(word)) return word.slice(0, -2);
+  if (word.length > 1 && /[^s]s$/i.test(word)) return word.slice(0, -1);
+  return word;
+}
+
+/** Turn a path segment (`contact-properties`) into an identifier stem (`contact_property`). */
+function segToStem(seg: string): string {
+  return singularize(seg).replace(/[^a-zA-Z0-9]+/g, "_").toLowerCase();
+}
+
+interface Occurrence {
+  ep: EndpointInfo;
+  /** Index of the {param} segment in the path. */
+  segIdx: number;
+}
+
+/** Mutates endpoints in place; returns the same array for chaining. */
+export function disambiguateGenericPathParams(endpoints: EndpointInfo[]): EndpointInfo[] {
+  // param-name → parent-seg → occurrences
+  const byParamParent = new Map<string, Map<string, Occurrence[]>>();
+
+  for (const ep of endpoints) {
+    const segs = ep.path.split("/");
+    for (let i = 0; i < segs.length; i++) {
+      const m = /^\{([^}]+)\}$/.exec(segs[i]!);
+      if (!m) continue;
+      const paramName = m[1]!;
+      if (!GENERIC_PARAM_NAMES.has(paramName.toLowerCase())) continue;
+      // Walk back to nearest non-param non-empty segment as "parent".
+      let parent: string | undefined;
+      for (let j = i - 1; j >= 0; j--) {
+        const s = segs[j]!;
+        if (s && !isParamSeg(s)) {
+          parent = s;
+          break;
+        }
+      }
+      if (!parent) continue;
+      let perParent = byParamParent.get(paramName);
+      if (!perParent) {
+        perParent = new Map();
+        byParamParent.set(paramName, perParent);
+      }
+      const arr = perParent.get(parent) ?? [];
+      arr.push({ ep, segIdx: i });
+      perParent.set(parent, arr);
+    }
+  }
+
+  for (const [paramName, perParent] of byParamParent) {
+    // Only rename when the param collides across ≥2 parents — single-resource
+    // use of `{id}` stays as-is to avoid churning user .env.yaml entries on
+    // APIs where the convention isn't a problem.
+    if (perParent.size < 2) continue;
+    const lowerParam = paramName.toLowerCase();
+    for (const [parent, occs] of perParent) {
+      const stem = segToStem(parent);
+      if (!stem) continue;
+      const newName = lowerParam === "id" ? `${stem}_id` : `${stem}_${lowerParam}`;
+      // Skip rename if newName collides with an unrelated existing name
+      // for the same endpoint (would corrupt parameters[]). Cheap guard.
+      for (const occ of occs) {
+        // ARV-183: preserve the original spec path before mutating, so
+        // downstream checks (status_code_conformance, response_headers_conformance)
+        // can still look up `doc.paths[...]` by string equality. Set only
+        // on first rename — subsequent renames of the same endpoint keep
+        // the truly original path.
+        if (occ.ep.originalPath === undefined) occ.ep.originalPath = occ.ep.path;
+        const segs = occ.ep.path.split("/");
+        segs[occ.segIdx] = `{${newName}}`;
+        occ.ep.path = segs.join("/");
+        const param = occ.ep.parameters.find(p => p.name === paramName && p.in === "path");
+        if (param) (param as { name: string }).name = newName;
+      }
+    }
+  }
+
+  return endpoints;
+}