@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/generator/index.ts

@@ -1,14 +0,0 @@
-export { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "./openapi-reader.ts";
-export { serializeSuite } from "./serializer.ts";
-export type { RawSuite, RawStep } from "./serializer.ts";
-export { scanCoveredEndpoints, filterUncoveredEndpoints, normalizePath, specPathToRegex } from "./coverage-scanner.ts";
-export type { CoveredEndpoint } from "./coverage-scanner.ts";
-export { analyzeEndpoints } from "./endpoint-warnings.ts";
-export type { EndpointWarning, WarningCode } from "./endpoint-warnings.ts";
-export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.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,297 +0,0 @@
-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 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 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);
-    return api as OpenAPIV3.Document;
-  }
-  const api = await dereference(specPath);
-  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;
-  if (!securitySchemes) return schemes;
-
-  for (const [name, schemeObj] of Object.entries(securitySchemes)) {
-    const scheme = schemeObj as OpenAPIV3.SecuritySchemeObject;
-    const info: SecuritySchemeInfo = {
-      name,
-      type: scheme.type as SecuritySchemeInfo["type"],
-    };
-    if (scheme.type === "http") {
-      info.scheme = scheme.scheme;
-      info.bearerFormat = scheme.bearerFormat;
-    }
-    if (scheme.type === "apiKey") {
-      info.in = scheme.in;
-      info.apiKeyName = scheme.name;
-    }
-    schemes.push(info);
-  }
-  return schemes;
-}
-
-export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
-  const endpoints: EndpointInfo[] = [];
-
-  if (!doc.paths) return endpoints;
-
-  for (const [path, pathItem] of Object.entries(doc.paths)) {
-    if (!pathItem) continue;
-
-    for (const method of HTTP_METHODS) {
-      const operation = pathItem[method] as OpenAPIV3.OperationObject | undefined;
-      if (!operation) continue;
-
-      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);
-        }
-      }
-
-      // 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,
-          );
-          if (existingIdx >= 0) {
-            parameters[existingIdx] = param;
-          } else {
-            parameters.push(param);
-          }
-        }
-      }
-
-      // 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;
-      if (operation.requestBody) {
-        const rb = operation.requestBody as OpenAPIV3.RequestBodyObject;
-        if (rb.content) {
-          // Prefer application/json, fall back to first available
-          const contentTypes = Object.keys(rb.content);
-          requestBodyContentType = contentTypes.includes("application/json")
-            ? "application/json"
-            : contentTypes[0];
-          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,
-                  };
-                }
-              }
-            }
-          }
-        }
-      }
-
-      // Responses
-      const responses: ResponseInfo[] = [];
-      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: parsedStatus,
-            description: resp.description || "",
-          };
-          if (resp.content) {
-            for (const ct of Object.keys(resp.content)) {
-              responseContentTypesSet.add(ct);
-            }
-            const jsonContent = resp.content["application/json"];
-            if (jsonContent?.schema) {
-              info.schema = jsonContent.schema as OpenAPIV3.SchemaObject;
-            }
-          }
-          responses.push(info);
-        }
-      }
-
-      // Security: operation-level overrides doc-level
-      const securityReqs = operation.security ?? doc.security ?? [];
-      const security = securityReqs.flatMap((req) => Object.keys(req));
-
-      // ETag optimistic locking: detect if endpoint requires If-Match header
-      const requiresEtag =
-        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(),
-        operationId: operation.operationId,
-        summary: operation.summary,
-        tags: operation.tags ?? [],
-        parameters,
-        requestBodySchema,
-        requestBodyContentType,
-        responseContentTypes: [...responseContentTypesSet],
-        responses,
-        security,
-        deprecated: (operation.deprecated ?? false) || isMarkedDeprecatedInText(operation.summary, operation.description, operation.operationId),
-        requiresEtag,
-        ...(extensions ? { extensions } : {}),
-      });
-    }
-  }
-
-  // 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;
-}

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

@@ -1,140 +0,0 @@
-/**
- * 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", "code"]);
-
-// 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";
-  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",
-      // 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) && !isSkippableSeg(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;
-}