@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/generator/suite-generator.ts

@@ -1,16 +1,63 @@
 import type { OpenAPIV3 } from "openapi-types";
 import type { EndpointInfo, SecuritySchemeInfo, CrudGroup } from "./types.ts";
 import type { RawSuite, RawStep } from "./serializer.ts";
-import { generateFromSchema, generateMultipartFromSchema } from "./data-factory.ts";
+import type { SourceMetadata } from "../parser/types.ts";
+import { generateFromSchema, generateMultipartFromSchema, isFkFixtureField, canonicalVarName, effectiveObjectShape } from "./data-factory.ts";
 import { groupEndpointsByTag } from "./chunker.ts";
+import { getAuthHeaders as sharedGetAuthHeaders } from "../probe/shared.ts";
+import { flattenToFormFields } from "../runner/form-encode.ts";
 
 // ──────────────────────────────────────────────
 // Helpers
 // ──────────────────────────────────────────────
 
-/** Convert OpenAPI path params {param} to test interpolation {{param}} */
-function convertPath(path: string): string {
-  return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+/**
+ * Singularize an English plural noun for use in suite names and capture
+ * variables. Handles the cases that matter for typical OpenAPI resource
+ * names — `properties → property`, `addresses → address`, `boxes → box`,
+ * `users → user`. Words that don't match any rule are returned unchanged
+ * (so already-singular `series`, `news`, `data`, etc. survive).
+ */
+export function singularizeResource(word: string): string {
+  if (word.length > 3 && /ies$/i.test(word)) return word.slice(0, -3) + "y";
+  // ARV-100 (F5): the inner alternative was `s` — but a single trailing `s`
+  // catches every regular plural whose stem ends in any vowel + `s` (e.g.
+  // `releases`, `phases`, `houses`), and `slice(-2)` then chops "es" instead
+  // of just "s". The result was `releas_id` / `phas_id` capture vars that
+  // matched nothing on the manifest side. Restrict the rule to the genuine
+  // sibilant double — `ss` — so `addresses → address` keeps working without
+  // dragging single-s plurals along.
+  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;
+}
+
+/**
+ * Build a `<resource>_id` capture/var name. Strips dashes so the result is
+ * a safe template variable identifier — `contact-properties` becomes
+ * `contact_property_id` rather than `contact-propertie_id` (TASK-214).
+ *
+ * ARV-100 (F5): always lowercase. Path-params/headers in fixtures-builder
+ * are normalised to lowercase (line 157), so capture vars must match — a
+ * `Groups` resource would otherwise produce `Group_id` while path-params on
+ * the same endpoint produce `group_id`, splitting the `{{var}}` namespace
+ * and triggering "Undefined variables" in `zond run`.
+ */
+export function resourceVar(resource: string, suffix: string): string {
+  const singular = singularizeResource(resource);
+  return `${singular.replace(/[^a-zA-Z0-9]+/g, "_")}_${suffix}`.toLowerCase();
+}
+
+/** Convert OpenAPI path params {param} to test interpolation {{param}}.
+ *  When `ambiguous` is given (ARV-369), a param name reused across
+ *  distinct resources becomes a resource-scoped var (`{{templates_code}}`)
+ *  instead of the raw name, so `.env.yaml` can hold distinct values per
+ *  resource instead of one value silently applying everywhere. */
+function convertPath(path: string, ambiguous?: Set<string>): string {
+  if (!ambiguous || ambiguous.size === 0) {
+    return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+  }
+  return path.replace(/\{([^}]+)\}/g, (_, name) => `{{${fixtureVarNameForPathParam(path, name, ambiguous)}}}`);
 }
 
 /**
@@ -56,6 +103,75 @@ function slugify(s: string): string {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
 
+/** Strip trailing API-version path segments (`v1`, `v30`, `version2`) so
+ *  resource-name derivation doesn't mistake a version marker for the
+ *  resource itself on APIs shaped `/api/<resource>/v{N}` (ARV-372). */
+export function stripTrailingVersionSegments(segments: string[]): string[] {
+  const out = [...segments];
+  while (out.length > 1 && /^v(ersion)?\d+$/i.test(out[out.length - 1]!)) {
+    out.pop();
+  }
+  return out;
+}
+
+/** Owning collection for a path-param: the last non-version path segment
+ *  before its `{name}` placeholder. Used to disambiguate a path-param name
+ *  (`code`, `id`, `key`) that's reused across genuinely distinct resources
+ *  (ARV-369) — e.g. `/api/templates/v30/{code}` → "templates" vs
+ *  `/api/macros/v30/{code}` → "macros". */
+// ARV-376: read-by-id accessor markers — kept in sync with the set in
+// path-param-disambig.ts. `/business-segment20/byid/{id}` is owned by
+// `business-segment20`, not the `byid` accessor verb.
+const ACCESSOR_MARKER_SEGS = new Set(["byid", "by-id", "by_id"]);
+
+export function owningCollectionForPathParam(path: string, paramName: string): string | null {
+  const marker = `{${paramName}}`;
+  const idx = path.indexOf(marker);
+  if (idx === -1) return null;
+  const segments = stripTrailingVersionSegments(path.slice(0, idx).split("/").filter(Boolean));
+  // Skip trailing accessor markers so the owner is the collection, not the
+  // `byid`/`by-code` verb — otherwise a param behind `/byid/{id}` and its
+  // sibling `DELETE /{id}` disagree on owner and get double-scoped.
+  let end = segments.length - 1;
+  while (end >= 0 && ACCESSOR_MARKER_SEGS.has(segments[end]!.toLowerCase())) end--;
+  return end >= 0 ? segments[end]! : null;
+}
+
+/** Path-param names reused by more than one distinct owning collection
+ *  across the whole spec — these need a resource-scoped fixture var name
+ *  (`templates_code`) instead of the raw name (`code`), otherwise one
+ *  `.env.yaml` value silently applies to unrelated resources (ARV-369). */
+export function computeAmbiguousPathParams(endpoints: EndpointInfo[]): Set<string> {
+  const owners = new Map<string, Set<string>>();
+  for (const ep of endpoints) {
+    for (const p of ep.parameters) {
+      if (p.in !== "path" || p.required === false) continue;
+      const owner = owningCollectionForPathParam(ep.path, p.name) ?? "";
+      if (!owners.has(p.name)) owners.set(p.name, new Set());
+      owners.get(p.name)!.add(owner);
+    }
+  }
+  const ambiguous = new Set<string>();
+  for (const [name, ownerSet] of owners) {
+    if (ownerSet.size > 1) ambiguous.add(name);
+  }
+  return ambiguous;
+}
+
+/** Resource-scoped fixture var name for a path-param, when ambiguous;
+ *  otherwise the raw param name (single-owner APIs — the common case —
+ *  keep producing the same var names as before ARV-369). */
+export function fixtureVarNameForPathParam(
+  path: string,
+  paramName: string,
+  ambiguous: Set<string>,
+): string {
+  if (!ambiguous.has(paramName)) return paramName;
+  const owner = owningCollectionForPathParam(path, paramName);
+  if (!owner) return paramName;
+  return `${owner.replace(/[^a-zA-Z0-9]+/g, "_")}_${paramName}`;
+}
+
 function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -73,11 +189,32 @@ function selectHealthcheckEndpoint(gets: EndpointInfo[]): EndpointInfo | undefin
   );
 }
 
+/**
+ * Pick the success status the test should assert.
+ *
+ * Order:
+ *   1. First 2xx declared in the spec (most authoritative).
+ *   2. Method-aware default when the spec lists only non-2xx responses or none
+ *      at all (many OpenAPI specs is silent for several mutating endpoints — the
+ *      actual runtime returns 201/204, while the old default of 200 caused
+ *      tests to fail at runtime). We never assert a 4xx/5xx as the success
+ *      status — that would generate guaranteed-failing tests.
+ */
 function getExpectedStatus(ep: EndpointInfo): number {
   const success = ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300);
   if (success) return success.statusCode;
-  if (ep.responses.length > 0) return ep.responses[0]!.statusCode;
-  return 200;
+  return defaultStatusByMethod(ep.method);
+}
+
+function defaultStatusByMethod(method: string): number {
+  switch (method.toUpperCase()) {
+    case "POST":
+      return 201;
+    case "DELETE":
+      return 204;
+    default:
+      return 200;
+  }
 }
 
 function getSuccessSchema(ep: EndpointInfo): OpenAPIV3.SchemaObject | undefined {
@@ -105,7 +242,7 @@ function getBodyAssertions(ep: EndpointInfo): Record<string, Record<string, stri
 }
 
 /** Derive a variable name for a security scheme's token */
-function schemeVarName(scheme: SecuritySchemeInfo, allSchemes: SecuritySchemeInfo[]): string {
+export function schemeVarName(scheme: SecuritySchemeInfo, allSchemes: SecuritySchemeInfo[]): string {
   // Count how many bearer-like schemes exist
   const bearerSchemes = allSchemes.filter(s =>
     (s.type === "http" && (s.scheme === "bearer" || !s.scheme)) ||
@@ -122,29 +259,7 @@ function getAuthHeaders(
   ep: EndpointInfo,
   schemes: SecuritySchemeInfo[],
 ): Record<string, string> | undefined {
-  if (ep.security.length === 0) return undefined;
-
-  for (const secName of ep.security) {
-    const scheme = schemes.find(s => s.name === secName);
-    if (!scheme) continue;
-
-    if (scheme.type === "http") {
-      if (scheme.scheme === "bearer" || !scheme.scheme) {
-        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
-      }
-      if (scheme.scheme === "basic") {
-        return { Authorization: `Basic {{${schemeVarName(scheme, schemes)}}}` };
-      }
-    }
-    if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
-      if (scheme.apiKeyName === "Authorization") {
-        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
-      }
-      return { [scheme.apiKeyName]: "{{api_key}}" };
-    }
-  }
-
-  return undefined;
+  return sharedGetAuthHeaders(ep, schemes, s => schemeVarName(s, schemes));
 }
 
 function getRequiredQueryParams(ep: EndpointInfo): Record<string, string> | undefined {
@@ -172,23 +287,95 @@ function getSuiteHeaders(
 
   const headerSets = endpoints.map(ep => getAuthHeaders(ep, schemes));
   const first = headerSets[0];
-  if (!first) return undefined;
+  if (!first) {
+    // ARV-212 (R13/F16): spec has no securitySchemes (GitHub publishes its
+    // OpenAPI this way) so per-endpoint auth-header derivation returns
+    // undefined for every step. When the API workspace nonetheless wires
+    // `auth_token` end-to-end (ARV-201 seeds it in .env.yaml on bare specs,
+    // and zond request / runner auto-attach Authorization: Bearer when
+    // auth_token is present), generated suites should not silently go
+    // unauth — that bricks them on the first rate-limited 60 requests.
+    // Fall back to a generic Bearer header at the suite level. The header
+    // is harmless when .secrets.yaml.auth_token is empty (zond runner
+    // still substitutes `{{auth_token}}` to an empty string, just like
+    // before; the server then 401s — same outcome as today).
+    if (schemes.length === 0 && _suiteDefaultAuthVar !== null) {
+      return { Authorization: `Bearer {{${_suiteDefaultAuthVar}}}` };
+    }
+    return undefined;
+  }
 
   const firstJson = JSON.stringify(first);
   const allSame = headerSets.every(h => JSON.stringify(h) === firstJson);
   return allSame ? first : undefined;
 }
 
-/** Find the best field to capture from POST response (for CRUD chains) */
-function getCaptureField(ep: EndpointInfo): string {
+// ARV-212 (R13/F16): generator-level "the caller wired auth_token in
+// .env.yaml even though the spec has no securitySchemes" hint. Set at the
+// top of generateSuites and consulted by getSuiteHeaders / generateCrudSuite
+// / generateSanitySuite. Module-scoped to avoid threading through ~7 call
+// sites. Always reset to null at the end of generateSuites so the helper
+// stays stateless from the caller's perspective.
+let _suiteDefaultAuthVar: string | null = null;
+
+/** Same module-scoping rationale as `_suiteDefaultAuthVar` above: computed
+ *  once from the full endpoint list at the top of generateSuites (ARV-369
+ *  needs the whole spec to detect a param-name collision), consulted by
+ *  `generateStep`'s path conversion. Reset to empty at the end of
+ *  generateSuites. */
+let _ambiguousPathParams: Set<string> = new Set();
+
+/** Common id-like field names looked up after `id` itself.
+ *  TASK-139: many real-world APIs return `slug`, `uuid`, `version`, `key`,
+ *  or `name` instead of an `id` field on create responses. Without these,
+ *  CRUD chains fall back to capturing `"id"` from a body that doesn't have
+ *  one, breaking the `{id}` substitution in follow-up reads. */
+const ID_LIKE_NAMES = ["slug", "uuid", "key", "version", "name"];
+
+/** Find the best field to capture from POST response (for CRUD chains).
+ *
+ *  Priority:
+ *    1. Field whose name matches the path-param (e.g. `{rule_id}` → `rule_id`
+ *       or `{slug}` → `slug`). The path-param name is the strongest hint —
+ *       whatever the response calls "the id of this resource" is what gets
+ *       interpolated back into the read/update/delete URLs.
+ *    2. `id` (most common case).
+ *    3. Conventional id-like names: `slug`, `uuid`, `key`, `version`, `name`
+ *       — but only if they are typed as a string (avoids capturing a `name`
+ *       object on resources that nest metadata).
+ *    4. Any field with `type: integer` or `format: uuid`.
+ *    5. Fallback: `"id"` (the YAML capture will simply be empty if absent —
+ *       the runner already handles this gracefully).
+ */
+function getCaptureField(ep: EndpointInfo, idParam?: string): string {
   const schema = getSuccessSchema(ep);
-  if (schema?.properties) {
-    if ("id" in schema.properties) return "id";
-    for (const [name, propSchema] of Object.entries(schema.properties)) {
-      const s = propSchema as OpenAPIV3.SchemaObject;
-      if (s.type === "integer" || s.format === "uuid") return name;
+  const props = schema?.properties;
+  if (!props) return "id";
+
+  // 1. Path-param name match.
+  if (idParam) {
+    if (idParam in props) return idParam;
+    // Also try the conventional `<resource>_id` ↔ `id` swap.
+    if (idParam.endsWith("_id") && "id" in props) return "id";
+  }
+
+  // 2. Plain `id`.
+  if ("id" in props) return "id";
+
+  // 3. Conventional id-like names (string-typed only).
+  for (const candidate of ID_LIKE_NAMES) {
+    if (candidate in props) {
+      const s = props[candidate] as OpenAPIV3.SchemaObject;
+      if (s.type === "string") return candidate;
     }
   }
+
+  // 4. Any integer or uuid-shaped field.
+  for (const [name, propSchema] of Object.entries(props)) {
+    const s = propSchema as OpenAPIV3.SchemaObject;
+    if (s.type === "integer" || s.format === "uuid") return name;
+  }
+
   return "id";
 }
 
@@ -200,10 +387,86 @@ function isAuthEndpoint(ep: EndpointInfo): boolean {
   return false;
 }
 
+// ──────────────────────────────────────────────
+// Provenance helpers
+// ──────────────────────────────────────────────
+
+function escapeJsonPointerSegment(s: string): string {
+  return s.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+function pickPrimaryStatus(status: number | number[]): number {
+  return Array.isArray(status) ? (status[0] ?? 200) : status;
+}
+
+/** Build step-level provenance for an endpoint + chosen response status. */
+export function buildStepSource(
+  ep: EndpointInfo,
+  statusOverride?: number | number[],
+): SourceMetadata {
+  const method = ep.method.toUpperCase();
+  const status = statusOverride ?? getExpectedStatus(ep);
+  const primary = pickPrimaryStatus(status);
+  const responseBranch = Array.isArray(status) ? status.map(String).join("|") : String(status);
+  const escapedPath = escapeJsonPointerSegment(ep.path);
+  return {
+    endpoint: `${method} ${ep.path}`,
+    response_branch: responseBranch,
+    schema_pointer: `#/paths/${escapedPath}/${method.toLowerCase()}/responses/${primary}`,
+  };
+}
+
+/** Build suite-level provenance for an openapi-generated suite. */
+export function buildOpenApiSuiteSource(specPath?: string): SourceMetadata | undefined {
+  if (!specPath) return undefined;
+  return {
+    type: "openapi-generated",
+    spec: specPath,
+    generator: "zond-generate",
+    generated_at: new Date().toISOString(),
+  };
+}
+
 // ──────────────────────────────────────────────
 // Public API
 // ──────────────────────────────────────────────
 
+/**
+ * ARV-45: swap FK-shaped required body fields for `{{fixture}}` references so
+ * their values come from `.env.yaml` instead of `{{$randomString}}`/`{{$uuid}}`
+ * junk that 400s and kills the CRUD chain at step 1. Field names that motivated
+ * this — `sequenceTypeCode`, `templateGroupCode` — are closed-vocab codes the
+ * generator can't guess. The var name is canonicalised (`sequence_type_code`)
+ * to match the manifest entry (fixtures-builder step 5); the HTTP body key
+ * keeps the raw spec spelling. Recurses into nested objects for nested FKs.
+ *
+ * Keep the detection predicate (`isFkFixtureField`) in lockstep with the
+ * manifest builder — every var the tests reference must appear in the manifest
+ * (decision-7).
+ */
+export function wireBodyFkRefs(schema: OpenAPIV3.SchemaObject, body: unknown): unknown {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+  // `effectiveObjectShape` merges allOf so allOf-wrapped bodies (the .NET/
+  // Swagger norm) resolve their properties — a direct schema.properties read
+  // misses every FK on those specs.
+  const { properties, required } = effectiveObjectShape(schema);
+  const out = body as Record<string, unknown>;
+  for (const [name, propSchema] of Object.entries(properties)) {
+    if (!(name in out)) continue;
+    if (required.has(name) && isFkFixtureField(name, propSchema)) {
+      out[name] = `{{${canonicalVarName(name)}}}`;
+    } else if (out[name] && typeof out[name] === "object" && !Array.isArray(out[name])) {
+      out[name] = wireBodyFkRefs(propSchema, out[name]);
+    }
+  }
+  return out;
+}
+
+/** Generate a request body from a schema with FK fields wired to fixtures. */
+function generateBody(schema: OpenAPIV3.SchemaObject): unknown {
+  return wireBodyFkRefs(schema, generateFromSchema(schema));
+}
+
 /** Generate a single test step from an EndpointInfo */
 export function generateStep(
   ep: EndpointInfo,
@@ -211,10 +474,11 @@ export function generateStep(
 ): RawStep {
   const method = ep.method.toUpperCase();
   const name = ep.operationId ?? ep.summary ?? `${method} ${ep.path}`;
-  const path = convertPath(ep.path);
+  const path = convertPath(ep.path, _ambiguousPathParams);
 
   const step: RawStep = {
     name,
+    source: buildStepSource(ep),
     [method]: path,
     expect: {
       status: getExpectedStatus(ep),
@@ -229,8 +493,14 @@ export function generateStep(
   if (["POST", "PUT", "PATCH"].includes(method) && ep.requestBodySchema) {
     if (ep.requestBodyContentType === "multipart/form-data") {
       step.multipart = generateMultipartFromSchema(ep.requestBodySchema);
+    } else if (ep.requestBodyContentType === "application/x-www-form-urlencoded") {
+      // ARV-149: form-encoded endpoints (Stripe v1 et al.) — emit `form:` so
+      // the runner posts URL-encoded bodies with bracket notation. Without
+      // this, generate baked `json:` blocks and every POST 400'd with
+      // "wrong content type".
+      step.form = flattenToFormFields(generateBody(ep.requestBodySchema));
     } else {
-      step.json = generateFromSchema(ep.requestBodySchema);
+      step.json = generateBody(ep.requestBodySchema);
     }
   }
 
@@ -247,33 +517,173 @@ export function generateStep(
   return step;
 }
 
-/** Detect CRUD groups from a list of endpoints */
+/** Strip a single trailing slash for comparison purposes. We never rewrite
+ *  endpoint paths in the spec — we just normalise the matching regex so
+ *  `POST /alerts/` + `GET /alerts/{id}/` lines up the same as the no-slash
+ *  variant. */
+function stripTrailingSlash(p: string): string {
+  return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+}
+
+/** Per-resource diagnostic record used by `zond generate --explain`.
+ *  Captures every POST candidate the detector considered and the verdict
+ *  with a human reason — so users can see "I have a CRUD-looking pair, why
+ *  didn't generate emit a chain?" without grepping the spec. */
+export interface CrudDetectionDiagnostic {
+  resource: string;
+  basePath: string;
+  postPath: string;
+  hasGetById: boolean;
+  hasUpdate: boolean;
+  hasDelete: boolean;
+  hasList: boolean;
+  verdict: "chain" | "skipped";
+  reason: string;
+}
+
+export interface DetectCrudResult {
+  groups: CrudGroup[];
+  diagnostics: CrudDetectionDiagnostic[];
+}
+
+/** Detect CRUD groups from a list of endpoints.
+ *
+ *  Match logic (TASK-139):
+ *    - basePath = POST endpoint's path with any trailing slash trimmed.
+ *    - item path = `<basePath>/{param}` with optional trailing slash.
+ *  This catches common SaaS-style `POST /alert-rules/` + `GET /alert-rules/{id}/`
+ *  pairs that previously fell through because the regex required the same
+ *  slash form on both. */
 export function detectCrudGroups(endpoints: EndpointInfo[]): CrudGroup[] {
+  return detectCrudGroupsWithDiagnostics(endpoints).groups;
+}
+
+export function detectCrudGroupsWithDiagnostics(
+  endpoints: EndpointInfo[],
+): DetectCrudResult {
   const groups: CrudGroup[] = [];
-  const postEndpoints = endpoints.filter(ep => ep.method.toUpperCase() === "POST" && !ep.deprecated);
+  const diagnostics: CrudDetectionDiagnostic[] = [];
+  const postEndpoints = endpoints.filter(
+    ep => ep.method.toUpperCase() === "POST" && !ep.deprecated,
+  );
 
   for (const createEp of postEndpoints) {
-    const basePath = createEp.path;
+    const basePath = stripTrailingSlash(createEp.path);
+    // ARV-372: skip trailing version segments (`v1`, `v30`) before taking the
+    // last segment as the resource name — otherwise every collection on a
+    // spec shaped `/api/<resource>/v{N}` (a common convention) resolves to
+    // the SAME resource name ("v30"), and multiple CRUD suites collide on
+    // the same `crud-<resource>.yaml` output filename, silently overwriting
+    // each other.
+    const resource = stripTrailingVersionSegments(basePath.split("/").filter(Boolean)).pop() ?? "resource";
+
+    // Match `<basePath>/{param}` with optional trailing slash. Tolerates
+    // both `POST /alerts/` + `GET /alerts/{id}` and `POST /alerts` +
+    // `GET /alerts/{id}/`, which some real-world specs mix.
+    const itemPattern = new RegExp(`^${escapeRegex(basePath)}/\\{([^}]+)\\}/?$`);
+    const itemEndpoints = endpoints.filter(
+      ep => !ep.deprecated && itemPattern.test(ep.path),
+    );
 
-    // Find item endpoints: basePath/{param}
-    const itemPattern = new RegExp(`^${escapeRegex(basePath)}/\\{([^}]+)\\}$`);
-    const itemEndpoints = endpoints.filter(ep => !ep.deprecated && itemPattern.test(ep.path));
+    // Fallback for "subdomain"/nested-item routing (common SaaS-style):
+    // create lives under one root (`/api/0/organizations/{org}/teams/`)
+    // but item-path lives under another (`/api/0/teams/{org}/{team}/`).
+    // The strict basePath/{id} regex misses these. Match instead by:
+    //   1. shared OpenAPI tag with the create operation,
+    //   2. terminal {param} matching the singular form of the resource
+    //      (`{team}` / `{team_id}` / `{team_id_or_slug}`).
+    let resolvedItemEndpoints = itemEndpoints;
+    if (resolvedItemEndpoints.length === 0) {
+      const singular = singularizeResource(resource).toLowerCase();
+      const itemTerminalRe = /\{([^}]+)\}\/?$/;
+      const matchesResourceParam = (p: string) => {
+        const m = p.match(itemTerminalRe);
+        if (!m) return false;
+        const param = m[1]!.toLowerCase();
+        return (
+          param === singular ||
+          param === `${singular}_id` ||
+          param === `${singular}_id_or_slug` ||
+          param === `${singular}_slug`
+        );
+      };
+      const createTags = new Set(createEp.tags ?? []);
+      const sharedTag = (ep: EndpointInfo) =>
+        (ep.tags ?? []).some(t => createTags.has(t));
+
+      resolvedItemEndpoints = endpoints.filter(
+        ep =>
+          !ep.deprecated &&
+          ep.path !== createEp.path &&
+          matchesResourceParam(ep.path) &&
+          sharedTag(ep),
+      );
+    }
 
-    if (itemEndpoints.length === 0) continue;
+    const read = resolvedItemEndpoints.find(ep => ep.method.toUpperCase() === "GET");
+    const update = resolvedItemEndpoints.find(
+      ep => ["PUT", "PATCH"].includes(ep.method.toUpperCase()),
+    );
+    const del = resolvedItemEndpoints.find(ep => ep.method.toUpperCase() === "DELETE");
+    // List endpoint matches with the same trailing-slash tolerance. ARV-376:
+    // also accept a `/list`, `/search`, `/find` verb suffix on the base path
+    // (`GET /api/deal-kind20/list`) — common in RPC-flavoured REST specs
+    // where the bare collection path has no GET.
+    const listStems = [basePath, `${basePath}/list`, `${basePath}/search`, `${basePath}/find`];
+    const list = endpoints.find(
+      ep =>
+        ep.method.toUpperCase() === "GET" &&
+        listStems.includes(stripTrailingSlash(ep.path)) &&
+        !ep.deprecated,
+    );
 
-    const itemPath = itemEndpoints[0]!.path;
-    const idMatch = itemPath.match(/\{([^}]+)\}$/);
-    if (!idMatch) continue;
-    const idParam = idMatch[1]!;
+    const diag: CrudDetectionDiagnostic = {
+      resource,
+      basePath,
+      postPath: createEp.path,
+      hasGetById: !!read,
+      hasUpdate: !!update,
+      hasDelete: !!del,
+      hasList: !!list,
+      verdict: "skipped",
+      reason: "",
+    };
 
-    const read = itemEndpoints.find(ep => ep.method.toUpperCase() === "GET");
-    if (!read) continue; // Minimum: POST + GET/{id}
+    if (resolvedItemEndpoints.length === 0) {
+      diag.reason = `no item endpoint matching ${basePath}/{...}`;
+      diagnostics.push(diag);
+      continue;
+    }
+    // TASK-260: accept headless chains — POST + (GET/PUT/PATCH/DELETE on /{id}).
+    // Resources with no GET-by-id (e.g. external-teams, some user-binding endpoints)
+    // were previously skipped entirely, even though POST captures the ID and PUT/DELETE
+    // can drive the chain on their own. The Read/Verify steps in the suite generator
+    // are already conditional on `group.read`, so headless chains generate cleanly.
+    if (!read && !update && !del) {
+      diag.reason = "item endpoint exists but no GET/PUT/PATCH/DELETE on /{id}";
+      diagnostics.push(diag);
+      continue;
+    }
 
-    const update = itemEndpoints.find(ep => ["PUT", "PATCH"].includes(ep.method.toUpperCase()));
-    const del = itemEndpoints.find(ep => ep.method.toUpperCase() === "DELETE");
-    const list = endpoints.find(ep => ep.method.toUpperCase() === "GET" && ep.path === basePath && !ep.deprecated);
+    const itemPath = resolvedItemEndpoints[0]!.path;
+    const idMatch = itemPath.match(/\{([^}]+)\}\/?$/);
+    if (!idMatch) {
+      diag.reason = "item path has no terminal {param}";
+      diagnostics.push(diag);
+      continue;
+    }
+    const idParam = idMatch[1]!;
 
-    const resource = basePath.split("/").filter(Boolean).pop() ?? "resource";
+    diag.verdict = "chain";
+    if (read) {
+      diag.reason = "POST + GET/{id} matched";
+    } else {
+      // TASK-260: explicit headless reason so `--explain` differentiates the
+      // two chain shapes — useful for debugging fixture flow.
+      const partner = update ? `${update.method.toUpperCase()}/{id}` : `DELETE/{id}`;
+      diag.reason = `POST + ${partner} matched (headless: no GET-by-id)`;
+    }
+    diagnostics.push(diag);
 
     groups.push({
       resource,
@@ -288,16 +698,44 @@ export function detectCrudGroups(endpoints: EndpointInfo[]): CrudGroup[] {
     });
   }
 
-  return groups;
+  return { groups, diagnostics };
 }
 
 /** Generate a CRUD chain suite from a CrudGroup */
+/** ARV-368: does the create's success response actually carry the capture
+ *  field? If not — a 204 no-body create, or a response schema without the id —
+ *  the runtime capture is empty and `{{captureVar}}` falls back to the
+ *  read-fixture of the SAME name (ARV-137 deliberately shares it). A PUT/DELETE
+ *  then targets a *pre-existing* resource whose id the user harvested for read
+ *  coverage — silent data-loss. Gate mutating chain steps on this so the suite
+ *  can only ever update/delete what it actually captured, never live data. */
+function createCapturesId(
+  create: EndpointInfo | undefined,
+  captureField: string,
+): boolean {
+  if (!create) return false;
+  const props = getSuccessSchema(create)?.properties;
+  return !!props && captureField in props;
+}
+
 export function generateCrudSuite(
   group: CrudGroup,
   securitySchemes: SecuritySchemeInfo[],
 ): RawSuite {
-  const captureField = group.create ? getCaptureField(group.create) : "id";
-  const captureVar = `${group.resource.replace(/s$/, "")}_id`;
+  const captureField = group.create ? getCaptureField(group.create, group.idParam) : "id";
+  // ARV-368: only chain PUT/DELETE when the create response yields the id we'd
+  // capture. Otherwise the capture is empty at runtime and the mutating step
+  // falls back to the shared read-fixture → deletes/overwrites pre-existing data.
+  const canChainMutations = createCapturesId(group.create, captureField);
+  // ARV-137: use the spec's path-param name as the capture var. Previously
+  // we synthesised `<resource>_id` via `resourceVar(...)`, which produced
+  // phantom manifest dupes whenever the spec named the path-param anything
+  // other than `<resource>_id` (e.g. `monitor_id_or_slug`, `version`, or
+  // collection-stem mismatches like resource=`saved`/idParam=`query_id`).
+  // Aligning on `group.idParam` keeps tests, manifest, and spec consistent.
+  // Fallback to `resourceVar` only when the group has no idParam (defensive
+  // — shouldn't happen for any group with a read/update/delete endpoint).
+  const captureVar = group.idParam || resourceVar(group.resource, "id");
   const tests: RawStep[] = [];
 
   const allEps = [group.create, group.list, group.read, group.update, group.delete].filter(Boolean) as EndpointInfo[];
@@ -322,7 +760,8 @@ export function generateCrudSuite(
   // 2. Read created
   if (group.read) {
     const step: RawStep = {
-      name: group.read.operationId ?? `Read created ${group.resource.replace(/s$/, "")}`,
+      name: group.read.operationId ?? `Read created ${singularizeResource(group.resource)}`,
+      source: buildStepSource(group.read),
       GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
       expect: {
         status: getExpectedStatus(group.read),
@@ -332,16 +771,18 @@ export function generateCrudSuite(
     tests.push(step);
   }
 
-  // 3. Update
-  if (group.update) {
+  // 3. Update (ARV-368: only if the chain self-captures its id — else the
+  //    fixture-fallback would overwrite a pre-existing resource)
+  if (group.update && canChainMutations) {
     const method = group.update.method.toUpperCase();
     const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
-    const etagVar = `${group.resource.replace(/s$/, "")}_etag`;
+    const etagVar = resourceVar(group.resource, "etag");
 
     // If endpoint requires ETag (optimistic locking), capture it from a GET step first
     if (group.update.requiresEtag && group.read) {
       tests.push({
-        name: `Get ETag before update ${group.resource.replace(/s$/, "")}`,
+        name: `Get ETag before update ${singularizeResource(group.resource)}`,
+        source: buildStepSource(group.read),
         GET: itemPath,
         expect: {
           status: getExpectedStatus(group.read),
@@ -351,7 +792,8 @@ export function generateCrudSuite(
     }
 
     const step: RawStep = {
-      name: group.update.operationId ?? `Update ${group.resource.replace(/s$/, "")}`,
+      name: group.update.operationId ?? `Update ${singularizeResource(group.resource)}`,
+      source: buildStepSource(group.update),
       [method]: itemPath,
       expect: {
         status: getExpectedStatus(group.update),
@@ -361,21 +803,23 @@ export function generateCrudSuite(
       step.headers = { "If-Match": `"{{${etagVar}}}"` };
     }
     if (group.update.requestBodySchema) {
-      step.json = generateFromSchema(group.update.requestBodySchema);
+      step.json = generateBody(group.update.requestBodySchema);
     }
     tests.push(step);
   }
 
-  // 4. Delete
-  if (group.delete) {
+  // 4. Delete (ARV-368: only if the chain self-captures its id — else the
+  //    fixture-fallback would DELETE a pre-existing resource → data-loss)
+  if (group.delete && canChainMutations) {
     const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
-    const etagVar = `${group.resource.replace(/s$/, "")}_etag`;
+    const etagVar = resourceVar(group.resource, "etag");
 
     // If delete requires ETag and update didn't already capture it, add a GET step
     const updateAlreadyCapturedEtag = group.update?.requiresEtag;
     if (group.delete.requiresEtag && group.read && !updateAlreadyCapturedEtag) {
       tests.push({
-        name: `Get ETag before delete ${group.resource.replace(/s$/, "")}`,
+        name: `Get ETag before delete ${singularizeResource(group.resource)}`,
+        source: buildStepSource(group.read),
         GET: itemPath,
         expect: {
           status: getExpectedStatus(group.read),
@@ -386,7 +830,8 @@ export function generateCrudSuite(
 
     // T44: cleanup must run even if earlier assertions failed (tainted captures)
     const step: RawStep = {
-      name: group.delete.operationId ?? `Delete ${group.resource.replace(/s$/, "")}`,
+      name: group.delete.operationId ?? `Delete ${singularizeResource(group.resource)}`,
+      source: buildStepSource(group.delete),
       DELETE: itemPath,
       always: true,
       expect: {
@@ -401,7 +846,8 @@ export function generateCrudSuite(
     // 5. Verify deleted — also always, so we confirm cleanup happened
     if (group.read) {
       tests.push({
-        name: `Verify ${group.resource.replace(/s$/, "")} deleted`,
+        name: `Verify ${singularizeResource(group.resource)} deleted`,
+        source: buildStepSource(group.read, 404),
         GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
         always: true,
         expect: {
@@ -594,7 +1040,7 @@ function generateConsistentAuthSuite(
 }
 
 /** Generate 1-2 minimal tests for quick connectivity and auth validation */
-export function generateSanitySuite(opts: {
+function generateSanitySuite(opts: {
   authEndpoints: EndpointInfo[];
   nonAuthGetEndpoints: EndpointInfo[];
   securitySchemes: SecuritySchemeInfo[];
@@ -631,11 +1077,23 @@ export function generateSanitySuite(opts: {
 export function generateSuites(opts: {
   endpoints: EndpointInfo[];
   securitySchemes: SecuritySchemeInfo[];
+  /** Path to OpenAPI spec, recorded in suite-level provenance. */
+  specPath?: string;
+  /** When true, deprecated endpoints are included instead of filtered out. */
+  includeDeprecated?: boolean;
+  /** ARV-212 (R13/F16): inject `Authorization: Bearer {{<varName>}}` at the
+   *  suite level when the spec declares no securitySchemes but the workspace
+   *  .env.yaml carries this auth-token variable. Lets generated suites talk
+   *  to bare-spec APIs (GitHub) without going unauth. */
+  defaultAuthVar?: string;
 }): RawSuite[] {
-  const { endpoints, securitySchemes } = opts;
+  const { endpoints, securitySchemes, specPath, includeDeprecated, defaultAuthVar } = opts;
+  _suiteDefaultAuthVar = defaultAuthVar ?? null;
+  _ambiguousPathParams = computeAmbiguousPathParams(endpoints);
 
-  // Filter deprecated
-  const active = endpoints.filter(ep => !ep.deprecated);
+  // Filter deprecated unless caller opted in. The list of skipped paths is
+  // exposed separately via `getSkippedDeprecated` for stdout reporting.
+  const active = includeDeprecated ? endpoints : endpoints.filter(ep => !ep.deprecated);
 
   // Separate auth endpoints
   const authEndpoints = active.filter(isAuthEndpoint);
@@ -670,27 +1128,52 @@ export function generateSuites(opts: {
     const paramlessGets = getEndpoints.filter(ep => !endpointHasPathParams(ep));
     const pathParamGets = getEndpoints.filter(ep => endpointHasPathParams(ep));
 
-    // Regular smoke: paramless GETs (e.g. list endpoints, health checks)
-    if (paramlessGets.length > 0) {
-      const tests = paramlessGets.map(ep => {
+    // Positive smoke: paramless GETs (no env needed) + path-param GETs
+    // (with skip_if guards). TASK-240 — unified naming convention:
+    // always emit `smoke-<tag>-positive.yaml`, never the bare
+    // `smoke-<tag>.yaml`, so file listings don't have to explain why a
+    // tag has only `-negative` (e.g. a vendor-specific tag) or why two
+    // siblings differ in suffix shape.
+    const positiveTests = [
+      ...paramlessGets.map(ep => {
         const step = generateStep(ep, securitySchemes);
         const seededPath = convertPathWithSeeds(ep.path, ep);
         (step as any)[ep.method.toUpperCase()] = seededPath;
         return step;
-      });
-      const headers = getSuiteHeaders(paramlessGets, securitySchemes);
+      }),
+      ...pathParamGets.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        // Path stays as {{param}} so user-provided env values flow in.
+        // skip_if guards an unset path-param without skipping paramless
+        // siblings that don't need a fixture.
+        const firstPathParam = ep.parameters.find(p => p.in === "path");
+        if (firstPathParam) {
+          step.skip_if = `{{${firstPathParam.name}}} ==`;
+        }
+        return step;
+      }),
+    ];
+
+    if (positiveTests.length > 0) {
+      const positiveEndpoints = [...paramlessGets, ...pathParamGets];
+      const headers = getSuiteHeaders(positiveEndpoints, securitySchemes);
+      // needs-id only when at least one test depends on a path-param
+      // fixture — coverage downgrades these suites when env is empty.
+      const tags = pathParamGets.length > 0
+        ? ["smoke", "positive", "needs-id"]
+        : ["smoke", "positive"];
 
       const suite: RawSuite = {
-        name: `${tagSlug}-smoke`,
-        tags: ["smoke"],
-        fileStem: `smoke-${tagSlug}`,
+        name: `${tagSlug}-smoke-positive`,
+        tags,
+        fileStem: `smoke-${tagSlug}-positive`,
         base_url: "{{base_url}}",
-        tests,
+        tests: positiveTests,
       };
 
       if (headers) {
         suite.headers = headers;
-        for (const t of tests) {
+        for (const t of positiveTests) {
           if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
             delete (t as any).headers;
           }
@@ -731,40 +1214,6 @@ export function generateSuites(opts: {
       suites.push(suite);
     }
 
-    // Positive smoke: path-param GETs with {{var}} placeholders + skip_if for unset env
-    if (pathParamGets.length > 0) {
-      const tests = pathParamGets.map(ep => {
-        const step = generateStep(ep, securitySchemes);
-        // Path stays as {{param}} so user-provided env values flow in
-        // Pick the first path param for skip_if guard (the resource ID)
-        const firstPathParam = ep.parameters.find(p => p.in === "path");
-        if (firstPathParam) {
-          step.skip_if = `{{${firstPathParam.name}}} ==`;
-        }
-        return step;
-      });
-      const headers = getSuiteHeaders(pathParamGets, securitySchemes);
-
-      const suite: RawSuite = {
-        name: `${tagSlug}-smoke-positive`,
-        tags: ["smoke", "positive", "needs-id"],
-        fileStem: `smoke-${tagSlug}-positive`,
-        base_url: "{{base_url}}",
-        tests,
-      };
-
-      if (headers) {
-        suite.headers = headers;
-        for (const t of tests) {
-          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
-            delete (t as any).headers;
-          }
-        }
-      }
-
-      suites.push(suite);
-    }
-
     // Non-GET endpoints: split reset/system endpoints out of smoke-unsafe
     const nonGetEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
     const resetEndpoints = nonGetEndpoints.filter(ep => RESET_PATH_RE.test(ep.path));
@@ -836,5 +1285,17 @@ export function generateSuites(opts: {
   const nonAuthGetEndpoints = nonAuth.filter(ep => ep.method.toUpperCase() === "GET");
   const sanitySuite = generateSanitySuite({ authEndpoints, nonAuthGetEndpoints, securitySchemes });
 
-  return sanitySuite ? [sanitySuite, ...suites] : suites;
+  const allSuites = sanitySuite ? [sanitySuite, ...suites] : suites;
+
+  // Stamp suite-level provenance when a spec path is known.
+  const suiteSrc = buildOpenApiSuiteSource(specPath);
+  if (suiteSrc) {
+    for (const s of allSuites) {
+      s.source = suiteSrc;
+    }
+  }
+
+  _suiteDefaultAuthVar = null;                                                                  // ARV-212
+  _ambiguousPathParams = new Set();                                                              // ARV-369
+  return allSuites;
 }