@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/generator/describe.ts

@@ -25,7 +25,7 @@ export interface CompactEndpoint {
   deprecated: boolean;
 }
 
-export function generateTestSnippet(params: {
+function generateTestSnippet(params: {
   method: string;
   path: string;
   operationId?: string;

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

@@ -0,0 +1,332 @@
+/**
+ * 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 type { OpenAPIV3 } from "openapi-types";
+import { schemeVarName, resourceVar, computeAmbiguousPathParams, fixtureVarNameForPathParam, owningCollectionForPathParam } from "./suite-generator.ts";
+import type { ApiResourceMap } from "./resources-builder.ts";
+import { canonicalVarName, isFkFixtureField, effectiveObjectShape } from "./data-factory.ts";
+
+// canonicalVarName now lives in data-factory (leaf module, shared with the
+// suite generator). Re-exported here for back-compat: create-body.ts and
+// existing callers still import it from fixtures-builder.
+export { canonicalVarName };
+
+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, disambiguated by
+  //    owning resource when the raw name is genuinely reused across
+  //    distinct collections (ARV-369). Without this, a spec where
+  //    `{code}` appears under both `/macros/v30/{code}` and
+  //    `/templates/v30/{code}` collapses to ONE `code` fixture — one
+  //    `.env.yaml` value then silently misapplies to whichever resources
+  //    don't own it, producing false-negative 404s in generated suites.
+  //    Single-owner param names (the common case) keep their raw name,
+  //    unchanged from pre-ARV-369 behavior.
+  const ambiguousPathParams = computeAmbiguousPathParams(params.endpoints);
+  for (const ep of params.endpoints) {
+    for (const p of ep.parameters) {
+      if (p.in !== "path") continue;
+      if (p.required === false) continue;
+      const varName = fixtureVarNameForPathParam(ep.path, p.name, ambiguousPathParams);
+      let req = fixtures.get(varName);
+      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 = "";
+
+        const scopeNote = ambiguousPathParams.has(p.name)
+          ? ` Scoped to "${owningCollectionForPathParam(ep.path, p.name) ?? "?"}" — the raw name "${p.name}" is also used by other resources with unrelated ids.`
+          : "";
+        req = {
+          name: varName,
+          source: "path",
+          description: `Path parameter ${p.name}${schema?.format ? ` (${schema.format})` : schema?.type ? ` (${schema.type})` : ""}.${scopeNote} Set to a real id from your account, or leave blank to skip dependent tests.`,
+          affectedEndpoints: [],
+          required: true,
+          defaultValue,
+        };
+        fixtures.set(varName, 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 OpenAPIV3.SchemaObject | undefined;
+    if (!schema) continue;
+    // effectiveObjectShape merges allOf — .NET/Swagger bodies wrap models in
+    // allOf, so a direct schema.properties read misses every FK field.
+    const { properties, required } = effectiveObjectShape(schema);
+    if (Object.keys(properties).length === 0) continue;
+    for (const [fieldName, propSchema] of Object.entries(properties)) {
+      if (!required.has(fieldName)) continue;
+      // ARV-45: catch FK ids AND closed-vocab reference codes
+      // (`sequenceTypeCode`) the generator can't synthesise — kept in
+      // lockstep with `wireBodyFkRefs` in suite-generator so every var the
+      // tests reference appears here (decision-7 manifest contract).
+      if (!isFkFixtureField(fieldName, propSchema as OpenAPIV3.SchemaObject)) 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 / reference field "${fieldName}" consumed by ${epLabel(ep)} request body. Set to a real value 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,14 @@
 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";

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

@@ -1,15 +1,54 @@
+import { readFileSync } from "node:fs";
+import { rootCertificates } from "node:tls";
 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;
 
-export async function readOpenApiSpec(specPath: string, options?: { insecure?: boolean }): Promise<OpenAPIV3.Document> {
+export interface SpecFetchTlsOptions {
+  /** Disable TLS verification entirely (bun `--insecure`). Last resort. */
+  insecure?: boolean;
+  /** Path to a PEM CA bundle to trust in addition to the public roots.
+   *  Falls back to the `NODE_EXTRA_CA_CERTS` env var. */
+  caPath?: string;
+}
+
+/** MF1 (ARV-367): resolve the bun `fetch` `tls` option for a spec fetch so a
+ *  self-signed / internal corporate CA validates *without* disabling TLS.
+ *
+ *  Precedence: `insecure` (verification off) > explicit `caPath` /
+ *  `NODE_EXTRA_CA_CERTS` (extra CA APPENDED to the public roots — never
+ *  replacing them, so public specs keep validating) > default (undefined).
+ *  Returns undefined when nothing special is needed. Throws if a CA path is
+ *  set but unreadable — a misconfigured CA should surface, not fall through
+ *  to a confusing "self signed certificate" error. */
+export function resolveSpecFetchTls(
+  options?: SpecFetchTlsOptions,
+): { rejectUnauthorized: false } | { ca: string[] } | undefined {
+  if (options?.insecure) return { rejectUnauthorized: false };
+  const caPath = options?.caPath ?? process.env.NODE_EXTRA_CA_CERTS;
+  if (caPath) {
+    let extra: string;
+    try {
+      extra = readFileSync(caPath, "utf8");
+    } catch (e) {
+      throw new Error(
+        `CA bundle not readable: ${caPath} (${(e as Error).message}). ` +
+          `Set --ca / NODE_EXTRA_CA_CERTS to a valid PEM file, or use --insecure.`,
+      );
+    }
+    if (extra.trim()) return { ca: [extra, ...rootCertificates] };
+  }
+  return undefined;
+}
+
+export async function readOpenApiSpec(specPath: string, options?: SpecFetchTlsOptions): Promise<OpenAPIV3.Document> {
   // For HTTP URLs, fetch the spec first then dereference the parsed object
   if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
-    const resp = await fetch(specPath, {
-      ...(options?.insecure ? { tls: { rejectUnauthorized: false } } : {}),
-    });
+    const tls = resolveSpecFetchTls(options);
+    const resp = await fetch(specPath, { ...(tls ? { tls } : {}) });
     if (!resp.ok) throw new Error(`Failed to fetch spec: ${resp.status} ${resp.statusText}`);
     const spec = await resp.json();
     const api = await dereference(spec as string);
@@ -19,6 +58,29 @@ export async function readOpenApiSpec(specPath: string, options?: { insecure?: b
   return api as OpenAPIV3.Document;
 }
 
+/** ARV-376: align declared path-param names with the path template when they
+ *  diverge (spec quirk: path `/byid/{id}` but param declared `byid_id`). The
+ *  template is authoritative for substitution, so unmatched params are renamed
+ *  to the unmatched template segment names, in positional order. No-op when
+ *  names already agree (the common, well-formed case). Mutates in place. */
+export function reconcilePathParamNames(
+  path: string,
+  parameters: OpenAPIV3.ParameterObject[],
+): void {
+  const tplNames = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]!);
+  if (tplNames.length === 0) return;
+  const pathParams = parameters.filter((p) => p.in === "path");
+  const declared = new Set(pathParams.map((p) => p.name));
+  const unmatchedTpl = tplNames.filter((n) => !declared.has(n));
+  const unmatchedParams = pathParams.filter((p) => !tplNames.includes(p.name));
+  // Only reconcile a clean 1:1 correspondence — if the counts differ we can't
+  // safely guess the mapping, so leave the (already odd) spec untouched.
+  if (unmatchedTpl.length === 0 || unmatchedTpl.length !== unmatchedParams.length) return;
+  unmatchedParams.forEach((p, i) => {
+    (p as { name: string }).name = unmatchedTpl[i]!;
+  });
+}
+
 export function extractSecuritySchemes(doc: OpenAPIV3.Document): SecuritySchemeInfo[] {
   const schemes: SecuritySchemeInfo[] = [];
   const securitySchemes = doc.components?.securitySchemes;
@@ -57,9 +119,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 +136,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,
@@ -79,6 +149,15 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
         }
       }
 
+      // ARV-376: reconcile a malformed spec where a path *template* segment
+      // (`/byid/{id}`) disagrees with the declared path *parameter* name
+      // (`byid_id`) — a docgen-style quirk. The path template is what the
+      // runner substitutes, so it wins: rename the diverging param(s) to the
+      // template segment name(s), positionally. Without this the fixture var
+      // (from the param) never matches the `{...}` in the path, and every
+      // downstream layer (disambig, manifest, resource-graph) diverges.
+      reconcilePathParamNames(path, parameters);
+
       // Request body schema + content type
       let requestBodySchema: OpenAPIV3.SchemaObject | undefined;
       let requestBodyContentType: string | undefined;
@@ -120,9 +199,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) {
@@ -147,6 +229,12 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
         responses.some(r => r.statusCode === 412) ||
         parameters.some(p => p.name.toLowerCase() === "if-match" && p.in === "header");
 
+      // ARV-189: harvest `x-*` vendor extensions. Operation-level wins on
+      // key collision over path-level so spec authors can default at the
+      // path and override per-operation. Empty result = undefined (avoids
+      // a churn-y `extensions: {}` field in serialised endpoint snapshots).
+      const extensions = collectExtensions(pathItem, operation);
+
       endpoints.push({
         path,
         method: method.toUpperCase(),
@@ -159,11 +247,51 @@ 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,
+        ...(extensions ? { extensions } : {}),
       });
     }
   }
 
-  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);
+}
+
+/** Collect `x-*` vendor extensions from a path item and operation,
+ *  with operation values winning on key collision. Returns undefined
+ *  when neither has any so callers can omit the field cleanly. */
+function collectExtensions(
+  pathItem: OpenAPIV3.PathItemObject,
+  operation: OpenAPIV3.OperationObject,
+): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(pathItem)) {
+    if (k.startsWith("x-")) out[k] = v;
+  }
+  for (const [k, v] of Object.entries(operation)) {
+    if (k.startsWith("x-")) out[k] = v;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** 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;
 }