@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/generator/schema-utils.ts

@@ -1,112 +0,0 @@
-import type { OpenAPIV3 } from "openapi-types";
-
-/**
- * Deep-clone an object, replacing circular references with the vendor-extension
- * sentinel `{ "x-circular": true }`. Uses WeakSet to track visited objects.
- *
- * Trade-off (intentional): we mark the SECOND visit of any shared object
- * (post-`dereference()` $ref-target reused under multiple parents) as
- * circular, not just true cycles. The alternative — a DFS path stack —
- * preserves every duplicate fresh, but blows the GitHub spec from 14 MB
- * to 106 MB on disk because shared `per_page`/`page`/`owner` params and
- * response schemas are re-cloned for every endpoint that references them.
- * Downstream tools that need param/schema visibility on every endpoint
- * (e.g. `zond api annotate auto`, ARV-262) handle this by re-reading the
- * source spec themselves rather than relying on `apis/<name>/spec.json`.
- *
- * Why a vendor extension and not `$ref`: the decycled doc is now written to
- * disk (apis/<name>/spec.json) and re-read by `@readme/openapi-parser` in
- * downstream commands (check spec, describe, generate). If the sentinel
- * carried a `$ref` field, the parser would try to resolve its value as a
- * JSON pointer / file path — e.g. `apis/stripe/[Circular]` — and fail
- * (ARV-146). `x-*` keys are explicitly reserved for vendor extensions in
- * OpenAPI 3.x and pass through every parser untouched.
- */
-export function decycleSchema(obj: unknown): unknown {
-  const seen = new WeakSet<object>();
-
-  function walk(value: unknown): unknown {
-    if (value === null || typeof value !== "object") return value;
-
-    if (Array.isArray(value)) {
-      return value.map(item => walk(item));
-    }
-
-    const obj = value as Record<string, unknown>;
-    if (seen.has(obj)) {
-      // ARV-262: parameter-shaped objects (have both `name` and `in`)
-      // appear post-`dereference()` as shared identities across every
-      // endpoint that $ref'd them — `per_page`, `page`, `owner`, etc.
-      // Past the first visit, the full `{"x-circular": true}` stub
-      // erases name+in and downstream tools (annotate auto, generator)
-      // can no longer tell what query/header that slot represented.
-      // Preserve name+in on revisit; schema/required/description still
-      // collapse so the bulk-size trade-off is unchanged (revisits
-      // grow by ~30 B each, vs. ~7×-blowup if we cloned everything).
-      if (typeof obj.name === "string" && typeof obj.in === "string") {
-        return { name: obj.name, in: obj.in };
-      }
-      return { "x-circular": true };
-    }
-    seen.add(obj);
-
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(obj)) {
-      result[key] = walk(obj[key]);
-    }
-    return result;
-  }
-
-  return walk(obj);
-}
-
-/**
- * Returns true if the schema is effectively `any` — no type, no properties, no constraints.
- */
-export function isAnySchema(schema: OpenAPIV3.SchemaObject | undefined): boolean {
-  if (!schema) return false;
-  return Object.keys(schema).length === 0 ||
-    (!schema.type && !schema.properties && !schema.enum && !schema.oneOf && !schema.allOf && !schema.anyOf);
-}
-
-/**
- * Compress an OpenAPI schema into a concise human-readable string.
- * E.g. { name: string (req), age: integer, tags: [string] }
- */
-export function compressSchema(schema: OpenAPIV3.SchemaObject, depth = 0): string {
-  if (depth > 2) return "{...}";
-
-  if (schema.type === "object" && schema.properties) {
-    const required = new Set(schema.required ?? []);
-    const fields = Object.entries(schema.properties).map(([key, propObj]) => {
-      const prop = propObj as OpenAPIV3.SchemaObject;
-      const type = prop.type ?? "any";
-      const flags: string[] = [];
-      if (required.has(key)) flags.push("req");
-      if (prop.format) flags.push(prop.format);
-      if (prop.enum) flags.push(`enum: ${prop.enum.join("|")}`);
-      const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
-      return `${key}: ${type}${flagStr}`;
-    });
-    return `{ ${fields.join(", ")} }`;
-  }
-
-  if (schema.type === "array") {
-    const items = schema.items as OpenAPIV3.SchemaObject | undefined;
-    if (items) return `[${compressSchema(items, depth + 1)}]`;
-    return "[]";
-  }
-
-  return schema.type ?? "any";
-}
-
-/**
- * Format an OpenAPI parameter into a concise string.
- * E.g. "limit: integer" or "id: string (req)"
- */
-export function formatParam(p: OpenAPIV3.ParameterObject): string {
-  const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
-  const type = schema?.type ?? "string";
-  const req = p.required ? " (req)" : "";
-  return `${p.name}: ${type}${req}`;
-}

package/src/core/generator/serializer.ts

@@ -1,343 +0,0 @@
-import { resolve } from "path";
-import type { SourceMetadata } from "../parser/types.ts";
-
-// ──────────────────────────────────────────────
-// Utility functions (moved from skeleton.ts)
-// ──────────────────────────────────────────────
-
-function isRelativeUrl(url: string): boolean {
-  return url.startsWith("/") && !url.includes("://");
-}
-
-function resolveSpecPath(specPath: string): string {
-  if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
-    return specPath;
-  }
-  return resolve(specPath);
-}
-
-function sanitizeEnvName(name: string): string {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
-}
-
-// ──────────────────────────────────────────────
-// Types for raw suite serialization
-// ──────────────────────────────────────────────
-
-export interface RawStep {
-  name: string;
-  source?: SourceMetadata;
-  [methodKey: string]: unknown;
-  expect: {
-    status?: number | number[];
-    body?: Record<string, Record<string, string>>;
-    headers?: Record<string, unknown>;
-  };
-}
-
-export interface RawSuite {
-  name: string;
-  setup?: boolean;
-  tags?: string[];
-  source?: SourceMetadata;
-  folder?: string;
-  fileStem?: string;
-  base_url?: string;
-  headers?: Record<string, string>;
-  tests: RawStep[];
-}
-
-// ──────────────────────────────────────────────
-// YAML serializer
-// ──────────────────────────────────────────────
-
-export function serializeSuite(suite: RawSuite): string {
-  const lines: string[] = [];
-  lines.push(`name: ${yamlScalar(suite.name)}`);
-  if (suite.setup) {
-    lines.push("setup: true");
-  }
-  if (suite.tags && suite.tags.length > 0) {
-    lines.push(`tags: [${suite.tags.join(", ")}]`);
-  }
-  if (suite.base_url) {
-    lines.push(`base_url: ${yamlScalar(suite.base_url)}`);
-  }
-  if (suite.headers && Object.keys(suite.headers).length > 0) {
-    lines.push("headers:");
-    for (const [hk, hv] of Object.entries(suite.headers)) {
-      lines.push(`  ${hk}: ${yamlScalar(String(hv))}`);
-    }
-  }
-  if (suite.source && Object.keys(suite.source).length > 0) {
-    lines.push("source:");
-    serializeValue(suite.source, 1, lines);
-  }
-  lines.push("tests:");
-
-  for (const test of suite.tests) {
-    lines.push(`  - name: ${yamlScalar(test.name)}`);
-
-    if (test.source && Object.keys(test.source).length > 0) {
-      lines.push("    source:");
-      serializeValue(test.source, 3, lines);
-    }
-
-    // Write method-as-key (the shorthand)
-    for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
-      if (method in test) {
-        lines.push(`    ${method}: ${test[method]}`);
-      }
-    }
-
-    // headers
-    if (test.headers && Object.keys(test.headers as Record<string, string>).length > 0) {
-      lines.push("    headers:");
-      for (const [hk, hv] of Object.entries(test.headers as Record<string, string>)) {
-        lines.push(`      ${hk}: ${yamlScalar(String(hv))}`);
-      }
-    }
-
-    // json body
-    if (test.json !== undefined) {
-      lines.push("    json:");
-      serializeValue(test.json, 3, lines);
-    }
-
-    // ARV-149: form body (application/x-www-form-urlencoded). The runner
-    // serialises this via URLSearchParams; values are flat strings with
-    // bracket notation for nested fields (e.g. `address[line1]`).
-    //
-    // ARV-162 (round-08 F19): form values are ALWAYS strings on the wire —
-    // x-www-form-urlencoded has no native numbers/bools/nulls. YAML parsing
-    // `phone: +1234567890` or `width: 12.5` as int/float makes `zond check
-    // tests` reject the suite ("expected string, received number"), and
-    // `zond run` silently skipped 21/68 generated Stripe suites this way.
-    // Force-quote every value regardless of shape; key still uses yamlScalar
-    // because bracket keys (`address[line1]`) need quoting too.
-    if (test.form !== undefined && typeof test.form === "object" && test.form !== null) {
-      const formEntries = Object.entries(test.form as Record<string, unknown>);
-      if (formEntries.length > 0) {
-        lines.push("    form:");
-        for (const [fk, fv] of formEntries) {
-          lines.push(`      ${yamlScalar(fk)}: "${escapeYamlDoubleQuoted(String(fv))}"`);
-        }
-      }
-    }
-
-    // query
-    if (test.query) {
-      lines.push("    query:");
-      serializeValue(test.query, 3, lines);
-    }
-
-    // skip_if
-    if (test.skip_if) {
-      lines.push(`    skip_if: ${yamlScalar(String(test.skip_if))}`);
-    }
-
-    // always (cleanup steps that survive cascade-skip on tainted captures)
-    if (test.always === true) {
-      lines.push("    always: true");
-    }
-
-    // retry_until
-    if (test.retry_until && typeof test.retry_until === "object") {
-      const rt = test.retry_until as Record<string, unknown>;
-      lines.push("    retry_until:");
-      if (rt.condition !== undefined) lines.push(`      condition: ${yamlScalar(String(rt.condition))}`);
-      if (rt.max_attempts !== undefined) lines.push(`      max_attempts: ${rt.max_attempts}`);
-      if (rt.delay_ms !== undefined) lines.push(`      delay_ms: ${rt.delay_ms}`);
-    }
-
-    // for_each
-    if (test.for_each && typeof test.for_each === "object") {
-      const fe = test.for_each as Record<string, unknown>;
-      lines.push("    for_each:");
-      if (fe.var !== undefined) lines.push(`      var: ${yamlScalar(String(fe.var))}`);
-      if (fe.in !== undefined) lines.push(`      in: ${yamlScalar(String(fe.in))}`);
-    }
-
-    // set
-    if (test.set && typeof test.set === "object") {
-      lines.push("    set:");
-      serializeValue(test.set, 3, lines);
-    }
-
-    // expect
-    const hasExpect = test.expect && (test.expect.status !== undefined || test.expect.body);
-    if (hasExpect) {
-      lines.push("    expect:");
-      if (test.expect.status !== undefined) {
-        if (Array.isArray(test.expect.status)) {
-          lines.push(`      status: [${test.expect.status.join(", ")}]`);
-        } else {
-          lines.push(`      status: ${test.expect.status}`);
-        }
-      }
-      if (test.expect.body) {
-        lines.push("      body:");
-        for (const [key, rule] of Object.entries(test.expect.body)) {
-          lines.push(`        ${key}:`);
-          for (const [rk, rv] of Object.entries(rule)) {
-            if (typeof rv === "object" && rv !== null) {
-              lines.push(`          ${rk}:`);
-              serializeValue(rv, 6, lines);
-            } else {
-              // Preserve scalar types — `not_equals: true` (boolean) must not
-              // become `not_equals: "true"` (string), or assertions silently
-              // mistype against real boolean fields.
-              lines.push(`          ${rk}: ${formatInlineValue(rv)}`);
-            }
-          }
-        }
-      }
-    }
-  }
-
-  return lines.join("\n") + "\n";
-}
-
-function serializeValue(value: unknown, indent: number, lines: string[]): void {
-  const prefix = "  ".repeat(indent);
-
-  if (value === null || value === undefined) {
-    lines.push(`${prefix}null`);
-    return;
-  }
-
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    lines.push(`${prefix}${yamlScalar(String(value))}`);
-    return;
-  }
-
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
-        const entries = Object.entries(item as Record<string, unknown>);
-        if (entries.length > 0) {
-          const [firstKey, firstVal] = entries[0]!;
-          if (typeof firstVal === "object" && firstVal !== null) {
-            if (isEmptyContainer(firstVal)) {
-              lines.push(`${prefix}- ${firstKey}: ${Array.isArray(firstVal) ? "[]" : "{}"}`);
-            } else {
-              lines.push(`${prefix}- ${firstKey}:`);
-              serializeValue(firstVal, indent + 1, lines);
-            }
-          } else {
-            lines.push(`${prefix}- ${firstKey}: ${formatInlineValue(firstVal)}`);
-          }
-          for (let i = 1; i < entries.length; i++) {
-            const [k, v] = entries[i]!;
-            if (typeof v === "object" && v !== null) {
-              if (isEmptyContainer(v)) {
-                lines.push(`${prefix}  ${k}: ${Array.isArray(v) ? "[]" : "{}"}`);
-              } else {
-                lines.push(`${prefix}  ${k}:`);
-                serializeValue(v, indent + 1, lines);
-              }
-            } else {
-              lines.push(`${prefix}  ${k}: ${formatInlineValue(v)}`);
-            }
-          }
-        } else {
-          lines.push(`${prefix}- {}`);
-        }
-      } else {
-        lines.push(`${prefix}- ${formatInlineValue(item)}`);
-      }
-    }
-    return;
-  }
-
-  if (typeof value === "object") {
-    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      if (typeof val === "object" && val !== null) {
-        if (isEmptyContainer(val)) {
-          lines.push(`${prefix}${key}: ${Array.isArray(val) ? "[]" : "{}"}`);
-        } else {
-          lines.push(`${prefix}${key}:`);
-          serializeValue(val, indent + 1, lines);
-        }
-      } else {
-        lines.push(`${prefix}${key}: ${formatInlineValue(val)}`);
-      }
-    }
-  }
-}
-
-/** Empty `{}` / `[]` written as a bare `key:` (no value, no children) is
- *  re-parsed by YAML as `null` — sending `null` for an `object`-typed field
- *  guarantees 422 against strict APIs. Emit inline flow form to preserve type. */
-function isEmptyContainer(val: unknown): boolean {
-  if (Array.isArray(val)) return val.length === 0;
-  if (typeof val === "object" && val !== null) return Object.keys(val).length === 0;
-  return false;
-}
-
-function formatInlineValue(val: unknown): string {
-  if (val === null || val === undefined) return "null";
-  if (typeof val === "string") return yamlScalar(val);
-  return String(val);
-}
-
-/** ARV-62 (feedback round-01 / F3): security probes emit attack payloads
- *  with raw CRLF (`crlf:`, header-injection) and other control bytes.
- *  When written into a double-quoted YAML scalar these *must* be escaped
- *  (`\r` / `\n` / `\t` / `\xNN`) — emitting the raw byte produces YAML
- *  that the parser rejects with "bad indentation of a mapping entry"
- *  (`zond run` then fails the whole suite at load-time before sending a
- *  single request). The check also covers `\r`, `\t`, `\x00–\x1f`, and
- *  `\x7f` so any other control byte that sneaks into a payload survives
- *  the YAML round-trip. */
-// eslint-disable-next-line no-control-regex
-const CONTROL_BYTE_RE = /[\x00-\x1f\x7f]/;
-function yamlScalar(value: string): string {
-  if (
-    value === "" ||
-    value === "true" ||
-    value === "false" ||
-    value === "null" ||
-    value.includes(":") ||
-    value.includes("#") ||
-    value.includes("'") ||
-    value.includes('"') ||
-    value.includes("{") ||
-    value.includes("}") ||
-    value.includes("[") ||
-    value.includes("]") ||
-    value.startsWith("&") ||
-    value.startsWith("*") ||
-    value.startsWith("!") ||
-    value.startsWith("%") ||
-    value.startsWith("@") ||
-    value.startsWith("`") ||
-    /^\d+$/.test(value) ||
-    CONTROL_BYTE_RE.test(value)
-  ) {
-    return `"${escapeYamlDoubleQuoted(value)}"`;
-  }
-  return value;
-}
-
-function escapeYamlDoubleQuoted(value: string): string {
-  let out = "";
-  for (let i = 0; i < value.length; i++) {
-    const ch = value[i]!;
-    const code = ch.charCodeAt(0);
-    if (ch === "\\") { out += "\\\\"; continue; }
-    if (ch === '"') { out += '\\"'; continue; }
-    if (ch === "\n") { out += "\\n"; continue; }
-    if (ch === "\r") { out += "\\r"; continue; }
-    if (ch === "\t") { out += "\\t"; continue; }
-    if (code < 0x20 || code === 0x7f) {
-      // YAML 1.2 allows \xNN for any byte in (0..0xff); use this for any
-      // control character that doesn't have a dedicated short escape
-      // (covers \x00–\x1f minus the three handled above, plus DEL).
-      out += "\\x" + code.toString(16).padStart(2, "0");
-      continue;
-    }
-    out += ch;
-  }
-  return out;
-}