@kirrosh/zond 0.20.0 → 0.22.0

package/src/core/diagnostics/db-analysis.ts

@@ -335,16 +335,25 @@ export function groupFailures<T extends FailureItem>(failures: T[], maxExamples
     const pattern = group.response_status
       ? `${group.response_status} ${group.failure_type}`
       : group.failure_type;
+    // 5xx (api_error) are critical backend bugs — never collapse them.
+    // Diagnose must surface every 5xx, otherwise users miss real
+    // regressions hidden behind a single sample.
+    const isApiError = group.failure_type === "api_error";
+    const showAll = isApiError || maxExamples === 0;
     grouped_failures.push({
       pattern,
       count: group.items.length,
       failure_type: group.failure_type,
       recommended_action: group.items[0]!.recommended_action,
       hint: group.hint,
-      examples: (maxExamples === 0 ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
+      examples: (showAll ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
       response_status: group.response_status,
     });
-    compactFailures.push(group.items[0]!);
+    if (isApiError) {
+      compactFailures.push(...group.items);
+    } else {
+      compactFailures.push(group.items[0]!);
+    }
   }
 
   return { grouped_failures, compactFailures };

package/src/core/diagnostics/render-md.ts

@@ -0,0 +1,112 @@
+import type { DiagnoseResult } from "./db-analysis.ts";
+
+/**
+ * Render a DiagnoseResult into a human-readable markdown digest.
+ * Output is the canonical body of the `zond://run/{id}/diagnosis` MCP resource.
+ */
+export function renderDiagnosisMarkdown(result: DiagnoseResult): string {
+  const { run, summary, agent_directive, env_issue, auth_hint, cascade_skips, failures, grouped_failures } = result;
+  const out: string[] = [];
+
+  const passed = summary.passed;
+  const total = summary.total;
+  const env = run.environment ?? "no env";
+  const duration = run.duration_ms !== null ? `${run.duration_ms}ms` : "unknown duration";
+
+  out.push(`# Run ${run.id} — ${passed}/${total} passed`);
+  out.push(`${run.started_at} · ${env} · ${duration}`);
+  out.push("");
+  out.push("## Summary");
+  out.push(`- total: ${summary.total}`);
+  out.push(`- passed: ${summary.passed}`);
+  out.push(`- failed: ${summary.failed} (api_errors: ${summary.api_errors}, assertion_failures: ${summary.assertion_failures}, network_errors: ${summary.network_errors})`);
+
+  if (agent_directive) {
+    out.push("");
+    out.push("## Agent directive");
+    out.push(agent_directive);
+  }
+
+  if (env_issue) {
+    out.push("");
+    out.push("## Env issue");
+    out.push(env_issue);
+  }
+
+  if (auth_hint) {
+    out.push("");
+    out.push("## Auth hint");
+    out.push(auth_hint);
+  }
+
+  if (cascade_skips && cascade_skips.length > 0) {
+    out.push("");
+    out.push("## Cascade skips");
+    for (const group of cascade_skips) {
+      out.push(`- **${group.capture_var}** — ${group.count} test${group.count === 1 ? "" : "s"} skipped`);
+      for (const example of group.examples) {
+        out.push(`  - ${example}`);
+      }
+    }
+  }
+
+  if (grouped_failures && grouped_failures.length > 0) {
+    out.push("");
+    out.push("## Failure groups");
+    for (const group of grouped_failures) {
+      out.push("");
+      out.push(`### ${group.pattern} — ${group.count} occurrence${group.count === 1 ? "" : "s"}`);
+      out.push(`recommended_action: \`${group.recommended_action}\``);
+      if (group.hint) out.push(`hint: ${group.hint}`);
+      if (group.examples.length > 0) {
+        out.push("examples:");
+        for (const example of group.examples) {
+          out.push(`- ${example}`);
+        }
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    out.push("");
+    out.push(grouped_failures && grouped_failures.length > 0 ? "## Representative failures" : "## Failures");
+    for (const f of failures) {
+      out.push("");
+      out.push(`### ${f.suite_name} > ${f.test_name}`);
+      const meta: string[] = [`failure_type: \`${f.failure_type}\``, `recommended_action: \`${f.recommended_action}\``];
+      if (f.suite_file) meta.push(`file: \`${f.suite_file}\``);
+      out.push(meta.join(" · "));
+      const requestLine = `${f.request_method ?? "?"} ${f.request_url ?? "?"}`;
+      const statusLine = f.response_status !== null ? ` → ${f.response_status}` : "";
+      out.push(`- request: ${requestLine}${statusLine}`);
+      if (f.error_message) out.push(`- error: ${f.error_message}`);
+      if (f.hint) out.push(`- hint: ${f.hint}`);
+      if (f.schema_hint) out.push(`- schema: ${f.schema_hint}`);
+      if (f.response_headers) {
+        const headerStr = Object.entries(f.response_headers).map(([k, v]) => `${k}: ${v}`).join(", ");
+        out.push(`- headers: ${headerStr}`);
+      }
+      if (f.response_body !== undefined) {
+        const bodyStr = typeof f.response_body === "string"
+          ? f.response_body
+          : JSON.stringify(f.response_body, null, 2);
+        const fenced = bodyStr.includes("\n") || bodyStr.length > 80;
+        if (fenced) {
+          out.push("- response_body:");
+          out.push("  ```");
+          for (const line of bodyStr.split("\n")) out.push(`  ${line}`);
+          out.push("  ```");
+        } else {
+          out.push(`- response_body: \`${bodyStr}\``);
+        }
+      }
+    }
+  }
+
+  if (failures.length === 0 && (!grouped_failures || grouped_failures.length === 0)) {
+    out.push("");
+    out.push("_No failures._");
+  }
+
+  return out.join("\n");
+}

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

@@ -0,0 +1,179 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "./types.ts";
+import { compressSchema, formatParam, isAnySchema } from "./schema-utils.ts";
+
+export interface CatalogEndpoint {
+  method: string;
+  path: string;
+  summary?: string;
+  tags: string[];
+  deprecated?: boolean;
+  parameters?: string[];
+  requestBody?: string;
+  responses: Array<{
+    status: number;
+    schema?: string;
+  }>;
+}
+
+export interface ApiCatalog {
+  generatedAt: string;
+  specSource: string;
+  specHash: string;
+  apiName?: string;
+  apiVersion?: string;
+  baseUrl?: string;
+  auth: string[];
+  endpointCount: number;
+  endpoints: CatalogEndpoint[];
+}
+
+export interface BuildCatalogParams {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+  specSource: string;
+  specHash: string;
+  apiName?: string;
+  apiVersion?: string;
+  baseUrl?: string;
+}
+
+function formatSecurityScheme(s: SecuritySchemeInfo): string {
+  let desc = `${s.name}: ${s.type}`;
+  if (s.scheme) desc += `/${s.scheme}`;
+  if (s.bearerFormat) desc += ` (${s.bearerFormat})`;
+  if (s.in && s.apiKeyName) desc += ` (${s.apiKeyName} in ${s.in})`;
+  return desc;
+}
+
+function formatParamWithLocation(p: import("openapi-types").OpenAPIV3.ParameterObject): string {
+  const base = formatParam(p);
+  // Insert location before (req) or at the end
+  const reqSuffix = " (req)";
+  if (base.endsWith(reqSuffix)) {
+    return `${base.slice(0, -reqSuffix.length)} (${p.in}, req)`;
+  }
+  return `${base} (${p.in})`;
+}
+
+function buildCatalogEndpoint(ep: EndpointInfo): CatalogEndpoint {
+  const result: CatalogEndpoint = {
+    method: ep.method.toUpperCase(),
+    path: ep.path,
+    tags: ep.tags,
+    responses: [],
+  };
+
+  if (ep.summary) result.summary = ep.summary;
+  if (ep.deprecated) result.deprecated = true;
+
+  if (ep.parameters.length > 0) {
+    result.parameters = ep.parameters.map(formatParamWithLocation);
+  }
+
+  if (ep.requestBodySchema) {
+    result.requestBody = isAnySchema(ep.requestBodySchema)
+      ? "any"
+      : compressSchema(ep.requestBodySchema);
+  }
+
+  for (const resp of ep.responses) {
+    const entry: { status: number; schema?: string } = { status: resp.statusCode };
+    if (resp.schema && !isAnySchema(resp.schema)) {
+      entry.schema = compressSchema(resp.schema);
+    }
+    result.responses.push(entry);
+  }
+
+  return result;
+}
+
+export function buildCatalog(params: BuildCatalogParams): ApiCatalog {
+  return {
+    generatedAt: new Date().toISOString(),
+    specSource: params.specSource,
+    specHash: params.specHash,
+    ...(params.apiName ? { apiName: params.apiName } : {}),
+    ...(params.apiVersion ? { apiVersion: params.apiVersion } : {}),
+    ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
+    auth: params.securitySchemes.map(formatSecurityScheme),
+    endpointCount: params.endpoints.length,
+    endpoints: params.endpoints.map(buildCatalogEndpoint),
+  };
+}
+
+// --- YAML serialization ---
+
+function yamlEscape(value: string): string {
+  if (/[:{}\[\],&*#?|<>=!%@`"']/.test(value) || value.includes("\n")) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function yamlScalar(value: unknown): string {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return yamlEscape(String(value));
+}
+
+export function serializeCatalog(catalog: ApiCatalog): string {
+  const lines: string[] = [];
+  lines.push("# Auto-generated by zond. Regenerate with: zond catalog <spec>");
+  lines.push(`generatedAt: ${yamlScalar(catalog.generatedAt)}`);
+  lines.push(`specSource: ${yamlScalar(catalog.specSource)}`);
+  lines.push(`specHash: ${yamlScalar(catalog.specHash)}`);
+  if (catalog.apiName) lines.push(`apiName: ${yamlScalar(catalog.apiName)}`);
+  if (catalog.apiVersion) lines.push(`apiVersion: ${yamlScalar(catalog.apiVersion)}`);
+  if (catalog.baseUrl) lines.push(`baseUrl: ${yamlScalar(catalog.baseUrl)}`);
+  lines.push(`endpointCount: ${catalog.endpointCount}`);
+
+  // Auth
+  if (catalog.auth.length > 0) {
+    lines.push("auth:");
+    for (const a of catalog.auth) {
+      lines.push(`  - ${yamlScalar(a)}`);
+    }
+  } else {
+    lines.push("auth: []");
+  }
+
+  // Endpoints
+  if (catalog.endpoints.length === 0) {
+    lines.push("endpoints: []");
+    return lines.join("\n") + "\n";
+  }
+  lines.push("endpoints:");
+  for (const ep of catalog.endpoints) {
+    lines.push(`  - method: ${ep.method}`);
+    lines.push(`    path: ${yamlScalar(ep.path)}`);
+    if (ep.summary) lines.push(`    summary: ${yamlScalar(ep.summary)}`);
+    if (ep.tags.length > 0) {
+      lines.push(`    tags: [${ep.tags.map(yamlScalar).join(", ")}]`);
+    }
+    if (ep.deprecated) lines.push(`    deprecated: true`);
+
+    if (ep.parameters && ep.parameters.length > 0) {
+      lines.push(`    parameters:`);
+      for (const p of ep.parameters) {
+        lines.push(`      - ${yamlScalar(p)}`);
+      }
+    }
+
+    if (ep.requestBody) {
+      lines.push(`    requestBody: ${yamlScalar(ep.requestBody)}`);
+    }
+
+    if (ep.responses.length > 0) {
+      lines.push(`    responses:`);
+      for (const r of ep.responses) {
+        if (r.schema) {
+          lines.push(`      - status: ${r.status}`);
+          lines.push(`        schema: ${yamlScalar(r.schema)}`);
+        } else {
+          lines.push(`      - status: ${r.status}`);
+        }
+      }
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}

package/src/core/generator/chunker.ts

@@ -39,9 +39,21 @@ export function planChunks(endpoints: EndpointInfo[]): ChunkPlan {
 
 /** Filter endpoints that have the given tag (case-insensitive) */
 export function filterByTag(endpoints: EndpointInfo[], tag: string): EndpointInfo[] {
-  const lower = tag.toLowerCase();
+  const lower = tag.trim().toLowerCase();
   if (lower === "untagged") {
     return endpoints.filter(ep => ep.tags.length === 0);
   }
-  return endpoints.filter(ep => ep.tags.some(t => t.toLowerCase() === lower));
+  return endpoints.filter(ep => ep.tags.some(t => t.trim().toLowerCase() === lower));
+}
+
+/** Collect the unique set of tags across all endpoints (sorted, original casing). */
+export function collectTags(endpoints: EndpointInfo[]): string[] {
+  const seen = new Map<string, string>();
+  for (const ep of endpoints) {
+    for (const t of ep.tags) {
+      const key = t.trim().toLowerCase();
+      if (!seen.has(key)) seen.set(key, t.trim());
+    }
+  }
+  return Array.from(seen.values()).sort((a, b) => a.localeCompare(b));
 }

package/src/core/generator/data-factory.ts

@@ -11,6 +11,12 @@ export function generateFromSchema(
 ): unknown {
   if (_depth > 5) return {};
 
+  // Highest-priority signal: explicit example from spec.
+  // Beats enum, format, heuristics — the spec author told us what to send.
+  if (schema.example !== undefined) {
+    return schema.example;
+  }
+
   // allOf: merge all schemas
   if (schema.allOf) {
     const merged: OpenAPIV3.SchemaObject = { type: "object", properties: {} };
@@ -31,15 +37,26 @@ export function generateFromSchema(
     return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
   }
 
-  // enum: first value
+  // enum: first value (always valid for the API contract)
   if (schema.enum && schema.enum.length > 0) {
     return schema.enum[0];
   }
 
-  // uuid format overrides type (e.g. integer fields with format: uuid)
-  if (schema.format === "uuid") return "{{$uuid}}";
-
-  switch (schema.type) {
+  // Format-based placeholders override type resolution. Schemas in the wild
+  // commonly carry `format` without an explicit `type` (loosely-defined specs)
+  // or with `type: ["string", "null"]` (OpenAPI 3.1 nullable). Falling through
+  // to the type switch in those cases dropped us into the default branch and
+  // produced `{{$randomString}}` for `format: email` — TASK-86 regression.
+  const formatPlaceholder = formatToPlaceholder(schema.format);
+  if (formatPlaceholder !== undefined) return formatPlaceholder;
+
+  // OpenAPI 3.1: type can be `["string", "null"]`. Collapse to the first
+  // non-null entry so the switch below routes correctly.
+  const effectiveType = Array.isArray(schema.type)
+    ? (schema.type as string[]).find(t => t !== "null") as OpenAPIV3.SchemaObject["type"] | undefined
+    : schema.type;
+
+  switch (effectiveType) {
     case "string":
       return guessStringPlaceholder(schema, propertyName);
 
@@ -53,8 +70,9 @@ export function generateFromSchema(
       return true;
 
     case "array": {
-      if (schema.items) {
-        const item = generateFromSchema(schema.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
+      const arr = schema as OpenAPIV3.ArraySchemaObject;
+      if (arr.items) {
+        const item = generateFromSchema(arr.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
         return [item];
       }
       return [];
@@ -79,7 +97,7 @@ export function generateFromSchema(
         return { key1: "value1", key2: "value2" };
       }
       // Bare object with no properties
-      if (schema.type === "object") {
+      if (effectiveType === "object") {
         return {};
       }
       return "{{$randomString}}";
@@ -87,6 +105,27 @@ export function generateFromSchema(
   }
 }
 
+/**
+ * Map an OpenAPI `format` value to a zond generator placeholder. Returns
+ * undefined when the format is unknown or absent so callers can fall back
+ * to type / property-name heuristics. Exported for tests.
+ */
+export function formatToPlaceholder(format: string | undefined): string | undefined {
+  switch (format) {
+    case "email": return "{{$randomEmail}}";
+    case "uuid": return "{{$uuid}}";
+    case "date-time": return "{{$randomIsoDate}}";
+    case "date": return "{{$randomDate}}";
+    case "uri":
+    case "url": return "{{$randomUrl}}";
+    case "hostname": return "{{$randomFqdn}}";
+    case "ipv4": return "{{$randomIpv4}}";
+    case "ipv6": return "::1";
+    case "password": return "TestPass123!";
+    default: return undefined;
+  }
+}
+
 /**
  * Generate a multipart body object from an OpenAPI multipart/form-data schema.
  * Binary fields (format: binary/byte) become file upload objects; all others become strings.
@@ -112,16 +151,8 @@ export function generateMultipartFromSchema(
 }
 
 function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string): string {
-  // Format-based
-  if (schema.format === "email") return "{{$randomEmail}}";
-  if (schema.format === "uuid") return "{{$uuid}}";
-  if (schema.format === "date-time") return "2025-01-01T00:00:00Z";
-  if (schema.format === "date") return "2025-01-01";
-  if (schema.format === "uri" || schema.format === "url") return "https://example.com/test";
-  if (schema.format === "hostname") return "example.com";
-  if (schema.format === "ipv4") return "192.168.1.1";
-  if (schema.format === "ipv6") return "::1";
-  if (schema.format === "password") return "TestPass123!";
+  // Format-based dispatch already happened earlier in generateFromSchema;
+  // this branch only sees strings whose format is empty or unrecognised.
 
   // Name-based heuristics
   if (name) {
@@ -136,7 +167,7 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
       return "{{$randomName}}";
     }
     if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") {
-      return "https://example.com/test";
+      return "{{$randomUrl}}";
     }
     if (lower === "password" || lower.endsWith("_password")) {
       return "TestPass123!";

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

@@ -120,7 +120,7 @@ Use \`json:\` for JSON request bodies. Do NOT use \`body:\` — it is not a vali
 For form-encoded: use \`form:\` instead of \`json:\`.
 
 ### Built-in generators
-\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`, \`{{$randomUrl}}\` (uri/url), \`{{$randomFqdn}}\` (hostname), \`{{$randomIpv4}}\` (ipv4), \`{{$randomDate}}\` (date), \`{{$randomIsoDate}}\` (date-time)
 
 ### Variable capture & interpolation
 \`\`\`yaml

package/src/core/generator/index.ts

@@ -10,3 +10,5 @@ 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";

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

@@ -93,6 +93,24 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
           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,
+                  };
+                }
+              }
+            }
           }
         }
       }

package/src/core/generator/serializer.ts

@@ -27,7 +27,7 @@ export interface RawStep {
   name: string;
   [methodKey: string]: unknown;
   expect: {
-    status?: number;
+    status?: number | number[];
     body?: Record<string, Record<string, string>>;
     headers?: Record<string, unknown>;
   };
@@ -103,6 +103,11 @@ export function serializeSuite(suite: RawSuite): string {
       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>;
@@ -131,7 +136,11 @@ export function serializeSuite(suite: RawSuite): string {
     if (hasExpect) {
       lines.push("    expect:");
       if (test.expect.status !== undefined) {
-        lines.push(`      status: ${test.expect.status}`);
+        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:");