@kirrosh/zond 0.23.0 → 0.26.0

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

@@ -13,25 +13,15 @@
  */
 
 import type { EndpointInfo, SecuritySchemeInfo } from "./types.ts";
-import { schemeVarName, resourceVar } from "./suite-generator.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";
 
-/**
- * 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();
-}
+// 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";
 
@@ -137,13 +127,22 @@ export function buildApiFixtureManifest(params: BuildFixturesParams): ApiFixture
     }
   }
 
-  // 3. Required path params → one var per unique name
+  // 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 name = p.name;
-      let req = fixtures.get(name);
+      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 = "";
@@ -151,15 +150,18 @@ export function buildApiFixtureManifest(params: BuildFixturesParams): ApiFixture
         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,
+          name: varName,
           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.`,
+          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(name, req);
+        fixtures.set(varName, req);
       }
       pushAffected(req, ep);
     }
@@ -200,14 +202,19 @@ export function buildApiFixtureManifest(params: BuildFixturesParams): ApiFixture
   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;
+    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` —
@@ -223,7 +230,7 @@ export function buildApiFixtureManifest(params: BuildFixturesParams): ApiFixture
       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.`,
+        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: "",

package/src/core/generator/index.ts

@@ -12,5 +12,3 @@ export { buildApiResourceMap, serializeApiResourceMap } from "./resources-builde
 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,3 +1,5 @@
+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";
@@ -5,12 +7,48 @@ 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);
@@ -20,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;
@@ -88,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;
@@ -159,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(),
@@ -173,6 +249,7 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
         security,
         deprecated: (operation.deprecated ?? false) || isMarkedDeprecatedInText(operation.summary, operation.description, operation.operationId),
         requiresEtag,
+        ...(extensions ? { extensions } : {}),
       });
     }
   }
@@ -184,6 +261,23 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
   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

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

@@ -24,12 +24,35 @@
 
 import type { EndpointInfo } from "./types.ts";
 
-const GENERIC_PARAM_NAMES = new Set(["id", "slug", "uuid", "key", "name", "identifier"]);
+const GENERIC_PARAM_NAMES = new Set(["id", "slug", "uuid", "key", "name", "identifier", "code"]);
 
-function isParamSeg(seg: string | undefined): seg is string {
+// ARV-376: read-by-id accessor markers. `/business-segment20/byid/{id}` names
+// the resource `business-segment20`, not `byid` — the `byid` (or `by-id`)
+// segment is a "get by id" verb, not the owning collection. Without skipping
+// it, every `/*/byid/{id}` across the spec collapses to one global `byid_id`
+// var with no owner resource, so prepare-fixtures reports `miss-no-list`.
+const ACCESSOR_MARKER_SEGS = new Set(["byid", "by-id", "by_id"]);
+
+// ARV-381: version segments (`v30`, `v2`) sit between the collection and its
+// id/code param (`/api/macros/v30/{code}`). owningCollectionForPathParam +
+// CRUD resource-name derivation ALREADY strip these via
+// stripTrailingVersionSegments; the disambig parent-walk must skip them too,
+// or `macros_v30_code` (scoped past the version) has no matching resource in
+// the graph → miss-no-list. Same regex as stripTrailingVersionSegments.
+function isVersionSeg(seg: string): boolean {
+  return /^v(ersion)?\d+$/i.test(seg);
+}
+
+function isParamSeg(seg: string | undefined): boolean {
   return !!seg && /^\{[^}]+\}$/.test(seg);
 }
 
+/** Segments the parent-walk steps over to reach the owning collection:
+ *  read-by-id accessor markers and version segments. */
+function isSkippableSeg(seg: string): boolean {
+  return ACCESSOR_MARKER_SEGS.has(seg.toLowerCase()) || isVersionSeg(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";
@@ -61,11 +84,14 @@ export function disambiguateGenericPathParams(endpoints: EndpointInfo[]): Endpoi
       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".
+      // Walk back to nearest non-param non-empty segment as "parent",
+      // skipping read-by-id accessor markers (`byid`, ARV-376) and version
+      // segments (`v30`, ARV-381) so the owning collection — not an accessor
+      // verb or version marker — names the param.
       let parent: string | undefined;
       for (let j = i - 1; j >= 0; j--) {
         const s = segs[j]!;
-        if (s && !isParamSeg(s)) {
+        if (s && !isParamSeg(s) && !isSkippableSeg(s)) {
           parent = s;
           break;
         }