@kirrosh/zond 0.14.0 → 0.16.0

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

@@ -0,0 +1,351 @@
+import { getDb } from "../../db/schema.ts";
+import { listCollections, listRuns, getRunById, getResultsByRunId, getCollectionById } from "../../db/queries.ts";
+import { join } from "node:path";
+import { statusHint, classifyFailure, envHint, envCategory, schemaHint, computeSharedEnvIssue } from "./failure-hints.ts";
+
+export function truncateErrorMessage(raw: string | null | undefined, verbose?: boolean): string | undefined {
+  if (!raw) return undefined;
+  if (verbose || raw.length < 500) return raw;
+  const lines = raw.split(/\r?\n/);
+  const msgLines = [lines[0]!];
+  let traceCount = 0;
+  for (let i = 1; i < lines.length && traceCount < 3; i++) {
+    const line = lines[i]!;
+    if (/^\s+/.test(line) || /^\s*at\s/.test(line)) {
+      msgLines.push(line);
+      traceCount++;
+    }
+  }
+  const remaining = lines.length - msgLines.length;
+  if (remaining > 0) {
+    msgLines.push(`...[truncated ${remaining} lines]`);
+  }
+  return msgLines.join("\n");
+}
+
+export function parseBodySafe(raw: string | null | undefined): unknown {
+  if (!raw) return undefined;
+  const truncated = raw.length > 2000 ? raw.slice(0, 2000) + "\u2026[truncated]" : raw;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return truncated;
+  }
+}
+
+const USEFUL_HEADERS = new Set([
+  "content-type", "content-length", "location", "retry-after",
+  "www-authenticate", "allow",
+]);
+const USEFUL_PREFIXES = ["x-", "ratelimit"];
+
+export function filterHeaders(raw: string | null | undefined): Record<string, string> | undefined {
+  if (!raw) return undefined;
+  try {
+    const h = JSON.parse(raw) as Record<string, string>;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(h)) {
+      const l = k.toLowerCase();
+      if (USEFUL_HEADERS.has(l) || USEFUL_PREFIXES.some(p => l.startsWith(p))) {
+        out[k] = v;
+      }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  } catch { return undefined; }
+}
+
+export interface RunDetail {
+  run: {
+    id: number;
+    started_at: string;
+    finished_at: string | null;
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    trigger: string | null;
+    environment: string | null;
+    duration_ms: number | null;
+  };
+  results: Array<{
+    suite_name: string;
+    test_name: string;
+    status: string;
+    duration_ms: number | null;
+    request_method: string | null;
+    request_url: string | null;
+    response_status: number | null;
+    error_message?: string;
+    assertions: unknown;
+  }>;
+}
+
+export function getRunDetail(runId: number, verbose?: boolean, dbPath?: string): RunDetail {
+  getDb(dbPath);
+  const run = getRunById(runId);
+  if (!run) throw new Error(`Run ${runId} not found`);
+  const results = getResultsByRunId(runId);
+  return {
+    run: {
+      id: run.id,
+      started_at: run.started_at,
+      finished_at: run.finished_at,
+      total: run.total,
+      passed: run.passed,
+      failed: run.failed,
+      skipped: run.skipped,
+      trigger: run.trigger,
+      environment: run.environment,
+      duration_ms: run.duration_ms,
+    },
+    results: results.map(r => ({
+      suite_name: r.suite_name,
+      test_name: r.test_name,
+      status: r.status,
+      duration_ms: r.duration_ms,
+      request_method: r.request_method,
+      request_url: r.request_url,
+      response_status: r.response_status,
+      error_message: truncateErrorMessage(r.error_message, verbose),
+      assertions: r.assertions,
+    })),
+  };
+}
+
+export interface FailureGroup {
+  pattern: string;
+  count: number;
+  failure_type: string;
+  hint?: string;
+  examples: string[];
+  response_status: number | null;
+}
+
+export interface DiagnoseResult {
+  run: {
+    id: number;
+    started_at: string;
+    environment: string | null;
+    duration_ms: number | null;
+  };
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    api_errors: number;
+    assertion_failures: number;
+    network_errors: number;
+  };
+  env_issue?: string;
+  failures: Array<{
+    suite_name: string;
+    test_name: string;
+    suite_file?: string;
+    status: string;
+    failure_type: string;
+    error_message?: string;
+    request_method: string | null;
+    request_url: string | null;
+    response_status: number | null;
+    hint?: string;
+    schema_hint?: string;
+    response_body?: unknown;
+    response_headers?: Record<string, string>;
+    assertions: unknown;
+    duration_ms: number | null;
+  }>;
+  grouped_failures?: FailureGroup[];
+}
+
+export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string): DiagnoseResult {
+  getDb(dbPath);
+  const diagRun = getRunById(runId);
+  if (!diagRun) throw new Error(`Run ${runId} not found`);
+
+  let envFilePath: string | undefined;
+  if (diagRun.collection_id) {
+    const collection = getCollectionById(diagRun.collection_id);
+    if (collection?.base_dir) {
+      envFilePath = join(collection.base_dir, ".env.yaml").replace(/\\/g, "/");
+    }
+  }
+
+  const allResults = getResultsByRunId(runId);
+  const failures = allResults
+    .filter(r => r.status === "fail" || r.status === "error")
+    .map(r => {
+      const hint = envHint(r.request_url, r.error_message, envFilePath) ?? statusHint(r.response_status);
+      const failure_type = classifyFailure(r.status, r.response_status);
+      const sHint = schemaHint(failure_type, r.response_status);
+      return {
+        suite_name: r.suite_name,
+        test_name: r.test_name,
+        ...(r.suite_file ? { suite_file: r.suite_file } : {}),
+        status: r.status,
+        failure_type,
+        error_message: truncateErrorMessage(r.error_message, verbose),
+        request_method: r.request_method,
+        request_url: r.request_url,
+        response_status: r.response_status,
+        ...(hint ? { hint } : {}),
+        ...(sHint ? { schema_hint: sHint } : {}),
+        response_body: parseBodySafe(r.response_body),
+        response_headers: filterHeaders(r.response_headers),
+        assertions: r.assertions,
+        duration_ms: r.duration_ms,
+      };
+    });
+
+  const sharedEnvHint = computeSharedEnvIssue(failures, envFilePath);
+
+  const apiErrors = failures.filter(f => f.failure_type === "api_error").length;
+  const assertionFailures = failures.filter(f => f.failure_type === "assertion_failed").length;
+  const networkErrors = failures.filter(f => f.failure_type === "network_error").length;
+
+  const { grouped_failures, compactFailures } = verbose
+    ? { grouped_failures: undefined, compactFailures: failures }
+    : groupFailures(failures);
+
+  return {
+    run: {
+      id: diagRun.id,
+      started_at: diagRun.started_at,
+      environment: diagRun.environment,
+      duration_ms: diagRun.duration_ms,
+    },
+    summary: {
+      total: diagRun.total,
+      passed: diagRun.passed,
+      failed: diagRun.failed,
+      api_errors: apiErrors,
+      assertion_failures: assertionFailures,
+      network_errors: networkErrors,
+    },
+    ...(sharedEnvHint ? { env_issue: sharedEnvHint } : {}),
+    failures: compactFailures,
+    ...(grouped_failures ? { grouped_failures } : {}),
+  };
+}
+
+type FailureItem = { suite_name: string; test_name: string; failure_type: string; hint?: string; response_status: number | null };
+
+/** Group similar failures for compact output. Exported for testing. */
+export function groupFailures<T extends FailureItem>(failures: T[]): { grouped_failures?: FailureGroup[]; compactFailures: T[] } {
+  if (failures.length <= 5) {
+    return { compactFailures: failures };
+  }
+
+  const groupMap = new Map<string, { items: T[]; failure_type: string; hint?: string; response_status: number | null }>();
+
+  for (const f of failures) {
+    const key = `${f.response_status ?? "null"}|${f.failure_type}`;
+    const existing = groupMap.get(key);
+    if (existing) {
+      existing.items.push(f);
+    } else {
+      groupMap.set(key, {
+        items: [f],
+        failure_type: f.failure_type,
+        hint: f.hint,
+        response_status: f.response_status,
+      });
+    }
+  }
+
+  const hasGroups = [...groupMap.values()].some(g => g.items.length > 2);
+  if (!hasGroups) {
+    return { compactFailures: failures };
+  }
+
+  const grouped_failures: FailureGroup[] = [];
+  const compactFailures: T[] = [];
+
+  for (const [, group] of groupMap) {
+    const pattern = group.response_status
+      ? `${group.response_status} ${group.failure_type}`
+      : group.failure_type;
+    grouped_failures.push({
+      pattern,
+      count: group.items.length,
+      failure_type: group.failure_type,
+      hint: group.hint,
+      examples: group.items.slice(0, 2).map(f => `${f.suite_name}/${f.test_name}`),
+      response_status: group.response_status,
+    });
+    compactFailures.push(group.items[0]!);
+  }
+
+  return { grouped_failures, compactFailures };
+}
+
+export interface CompareResult {
+  runA: { id: number; started_at: string };
+  runB: { id: number; started_at: string };
+  summary: {
+    regressions: number;
+    fixes: number;
+    unchanged: number;
+    newTests: number;
+    removedTests: number;
+  };
+  regressions: Array<{ suite: string; test: string; before: string; after: string }>;
+  fixes: Array<{ suite: string; test: string; before: string; after: string }>;
+  hasRegressions: boolean;
+}
+
+export function compareRuns(idA: number, idB: number, dbPath?: string): CompareResult {
+  getDb(dbPath);
+  const runARecord = getRunById(idA);
+  const runBRecord = getRunById(idB);
+  if (!runARecord) throw new Error(`Run #${idA} not found`);
+  if (!runBRecord) throw new Error(`Run #${idB} not found`);
+
+  const resultsA = getResultsByRunId(idA);
+  const resultsB = getResultsByRunId(idB);
+
+  const mapA = new Map<string, string>();
+  const mapB = new Map<string, string>();
+  for (const r of resultsA) mapA.set(`${r.suite_name}::${r.test_name}`, r.status);
+  for (const r of resultsB) mapB.set(`${r.suite_name}::${r.test_name}`, r.status);
+
+  const regressions: Array<{ suite: string; test: string; before: string; after: string }> = [];
+  const fixes: Array<{ suite: string; test: string; before: string; after: string }> = [];
+  let unchanged = 0;
+  let newTests = 0;
+  let removedTests = 0;
+
+  for (const [key, statusB] of mapB) {
+    const statusA = mapA.get(key);
+    if (statusA === undefined) { newTests++; continue; }
+    const [suite, test] = key.split("::") as [string, string];
+    const wasPass = statusA === "pass";
+    const isPass = statusB === "pass";
+    const wasFail = statusA === "fail" || statusA === "error";
+    const isFail = statusB === "fail" || statusB === "error";
+    if (wasPass && isFail) regressions.push({ suite, test, before: statusA, after: statusB });
+    else if (wasFail && isPass) fixes.push({ suite, test, before: statusA, after: statusB });
+    else unchanged++;
+  }
+  for (const key of mapA.keys()) {
+    if (!mapB.has(key)) removedTests++;
+  }
+
+  return {
+    runA: { id: idA, started_at: runARecord.started_at },
+    runB: { id: idB, started_at: runBRecord.started_at },
+    summary: { regressions: regressions.length, fixes: fixes.length, unchanged, newTests, removedTests },
+    regressions,
+    fixes,
+    hasRegressions: regressions.length > 0,
+  };
+}
+
+export function getCollections(dbPath?: string) {
+  getDb(dbPath);
+  return listCollections();
+}
+
+export function getRuns(limit?: number, dbPath?: string) {
+  getDb(dbPath);
+  return listRuns(limit ?? 20);
+}

package/src/core/diagnostics/failure-hints.ts

@@ -9,6 +9,7 @@ export function statusHint(status: number | null | undefined): string | null {
   if (status === 401 || status === 403) return "Auth failure — check auth_token/api_key in .env.yaml";
   if (status === 404) return "Resource not found — verify the path and ID";
   if (status === 400 || status === 422) return "Validation error — check request body fields match the schema";
+  if (status === 429) return "Rate limited — too many requests. Consider consolidating auth/login steps or adding delays between suites";
   return null;
 }
 

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

@@ -38,10 +38,10 @@ export function generateFromSchema(
       return guessStringPlaceholder(schema, propertyName);
 
     case "integer":
-      return guessIntPlaceholder(propertyName);
+      return guessIntPlaceholder(propertyName, schema);
 
     case "number":
-      return "{{$randomInt}}";
+      return 29.99;
 
     case "boolean":
       return true;
@@ -86,6 +86,11 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
   if (schema.format === "email") return "{{$randomEmail}}";
   if (schema.format === "uuid") return "{{$uuid}}";
   if (schema.format === "date-time" || schema.format === "date") return "2025-01-01T00:00:00Z";
+  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!";
 
   // Name-based heuristics
   if (name) {
@@ -99,17 +104,23 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
     if (lower === "name" || lower.endsWith("_name") || lower.endsWith("Name")) {
       return "{{$randomName}}";
     }
+    if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") {
+      return "https://example.com/test";
+    }
+    if (lower === "password" || lower.endsWith("_password")) {
+      return "TestPass123!";
+    }
+    if (lower === "phone" || lower === "telephone" || lower.endsWith("_phone")) {
+      return "+1234567890";
+    }
   }
 
   return "{{$randomString}}";
 }
 
-function guessIntPlaceholder(name?: string): string {
-  if (name) {
-    const lower = name.toLowerCase();
-    if (lower === "id" || lower.endsWith("_id") || lower.endsWith("Id")) {
-      return "{{$randomInt}}";
-    }
+function guessIntPlaceholder(name?: string, schema?: OpenAPIV3.SchemaObject): number | string {
+  if (schema?.minimum !== undefined && schema.minimum > 0) {
+    return schema.minimum;
   }
   return "{{$randomInt}}";
 }

package/src/core/generator/describe.ts

@@ -0,0 +1,250 @@
+import type { OpenAPIV3 } from "openapi-types";
+import { readOpenApiSpec } from "./openapi-reader.ts";
+import { decycleSchema } from "./schema-utils.ts";
+
+export interface DescribeEndpointResult {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated: boolean;
+  security: string[];
+  parameters: Record<string, object[]>;
+  requestBody?: object;
+  responses: Record<string, object>;
+  testSnippet: string;
+}
+
+export interface CompactEndpoint {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  deprecated: boolean;
+}
+
+export function generateTestSnippet(params: {
+  method: string;
+  path: string;
+  operationId?: string;
+  pathParams: string[];
+  queryParams: Array<{ name: string; required?: boolean }>;
+  requestBody?: { required?: boolean; schema?: OpenAPIV3.SchemaObject };
+  hasSecurity: boolean;
+  successStatus: string;
+}): string {
+  const { method, path, operationId, queryParams, requestBody, hasSecurity, successStatus } = params;
+
+  const urlPath = path.replace(/\{([^}]+)\}/g, (_, name) => `{{${name}}}`);
+  const url = `{{base_url}}${urlPath}`;
+
+  const lines: string[] = [];
+  const testName = operationId ?? `${method} ${path}`;
+  lines.push(`- name: "${testName}"`);
+  lines.push(`  ${method}: "${url}"`);
+
+  if (hasSecurity) {
+    lines.push(`  headers:`);
+    lines.push(`    Authorization: "Bearer {{auth_token}}"`);
+  }
+
+  const requiredQuery = queryParams.filter(p => p.required);
+  if (requiredQuery.length > 0) {
+    lines.push(`  query:`);
+    for (const p of requiredQuery) {
+      lines.push(`    ${p.name}: "{{${p.name}}}"`);
+    }
+  }
+
+  if (requestBody && ["POST", "PUT", "PATCH"].includes(method)) {
+    const schema = requestBody.schema as OpenAPIV3.SchemaObject | undefined;
+    const required = Array.isArray(schema?.required) ? schema.required : [];
+    const properties = schema?.properties as Record<string, OpenAPIV3.SchemaObject> | undefined;
+    if (properties && Object.keys(properties).length > 0) {
+      lines.push(`  json:`);
+      for (const [propName, propSchema] of Object.entries(properties)) {
+        if (!required.includes(propName)) continue;
+        const type = (propSchema as OpenAPIV3.SchemaObject).type ?? "string";
+        const placeholder = type === "integer" || type === "number" ? 0 : type === "boolean" ? false : `"{{${propName}}}"`;
+        lines.push(`    ${propName}: ${placeholder}`);
+      }
+    }
+  }
+
+  lines.push(`  expect:`);
+  lines.push(`    status: ${successStatus}`);
+
+  return lines.join("\n");
+}
+
+export async function describeEndpoint(
+  specPath: string,
+  method: string,
+  endpointPath: string,
+  options?: { insecure?: boolean },
+): Promise<DescribeEndpointResult> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+
+  const methodLower = method.toLowerCase() as OpenAPIV3.HttpMethods;
+  const normalizedPath = endpointPath.replace(/\/+$/, "") || "/";
+
+  let operation: OpenAPIV3.OperationObject | undefined;
+  let resolvedPath = normalizedPath;
+  const paths = doc.paths ?? {};
+
+  if (paths[normalizedPath]?.[methodLower]) {
+    operation = paths[normalizedPath][methodLower] as OpenAPIV3.OperationObject;
+  } else {
+    const lowerTarget = normalizedPath.toLowerCase();
+    for (const [p, pathItem] of Object.entries(paths)) {
+      if (p.toLowerCase() === lowerTarget && pathItem?.[methodLower]) {
+        operation = pathItem[methodLower] as OpenAPIV3.OperationObject;
+        resolvedPath = p;
+        break;
+      }
+    }
+  }
+
+  if (!operation) {
+    const available = Object.entries(paths).flatMap(([p, pathItem]) =>
+      Object.keys(pathItem ?? {})
+        .filter(k => ["get","post","put","patch","delete","head","options","trace"].includes(k))
+        .map(k => `${k.toUpperCase()} ${p}`)
+    ).sort();
+    throw new Error(`Endpoint ${method.toUpperCase()} ${endpointPath} not found in spec. Available: ${available.join(", ")}`);
+  }
+
+  const pathItem = paths[resolvedPath] ?? {};
+
+  const pathLevelParams = (pathItem.parameters ?? []) as OpenAPIV3.ParameterObject[];
+  const opLevelParams = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[];
+
+  const paramMap = new Map<string, OpenAPIV3.ParameterObject>();
+  for (const p of pathLevelParams) paramMap.set(`${p.in}:${p.name}`, p);
+  for (const p of opLevelParams) paramMap.set(`${p.in}:${p.name}`, p);
+
+  const grouped: Record<string, object[]> = { path: [], query: [], header: [], cookie: [] };
+  for (const p of paramMap.values()) {
+    const loc = p.in in grouped ? p.in : "query";
+    const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+    grouped[loc]!.push({
+      name: p.name,
+      required: p.required ?? false,
+      ...(schema?.type ? { type: schema.type } : {}),
+      ...(schema?.format ? { format: schema.format } : {}),
+      ...(schema?.enum ? { enum: schema.enum } : {}),
+      ...(schema?.default !== undefined ? { default: schema.default } : {}),
+      ...(p.description ? { description: p.description } : {}),
+    });
+  }
+
+  let requestBody: object | undefined;
+  if (operation.requestBody) {
+    const rb = operation.requestBody as OpenAPIV3.RequestBodyObject;
+    const contentTypes = Object.keys(rb.content ?? {});
+    const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
+    const mediaObj = preferredCt ? rb.content[preferredCt] : undefined;
+    requestBody = {
+      required: rb.required ?? false,
+      ...(preferredCt ? { contentType: preferredCt } : {}),
+      ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
+      ...(rb.description ? { description: rb.description } : {}),
+    };
+  }
+
+  const responses: Record<string, object> = {};
+  for (const [statusCode, respObj] of Object.entries(operation.responses ?? {})) {
+    const resp = respObj as OpenAPIV3.ResponseObject;
+    const contentTypes = Object.keys(resp.content ?? {});
+    const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
+    const mediaObj = preferredCt ? resp.content?.[preferredCt] : undefined;
+
+    const headers: Record<string, object> = {};
+    for (const [hName, hObj] of Object.entries(resp.headers ?? {})) {
+      const h = hObj as OpenAPIV3.HeaderObject;
+      headers[hName] = {
+        ...(h.description ? { description: h.description } : {}),
+        ...(h.schema ? { schema: h.schema } : {}),
+      };
+    }
+
+    responses[statusCode] = {
+      description: resp.description,
+      headers,
+      ...(preferredCt ? { contentType: preferredCt } : {}),
+      ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
+    };
+  }
+
+  const docSecurity = (doc.security ?? []) as OpenAPIV3.SecurityRequirementObject[];
+  const opSecurity = (operation.security ?? docSecurity) as OpenAPIV3.SecurityRequirementObject[];
+  const securityNames = [...new Set(opSecurity.flatMap(req => Object.keys(req)))];
+
+  const responseCodes = Object.keys(operation.responses ?? {});
+  const successStatus = responseCodes.find(c => c.startsWith("2")) ?? responseCodes[0] ?? "200";
+
+  const pathParamNames = [...paramMap.values()]
+    .filter(p => p.in === "path")
+    .map(p => p.name);
+  const queryParamsList = [...paramMap.values()]
+    .filter(p => p.in === "query")
+    .map(p => ({ name: p.name, required: p.required }));
+  const reqBodyForSnippet = requestBody
+    ? { required: (operation.requestBody as OpenAPIV3.RequestBodyObject)?.required, schema: (requestBody as any).schema }
+    : undefined;
+
+  const testSnippet = generateTestSnippet({
+    method: method.toUpperCase(),
+    path: resolvedPath,
+    operationId: operation.operationId,
+    pathParams: pathParamNames,
+    queryParams: queryParamsList,
+    requestBody: reqBodyForSnippet,
+    hasSecurity: securityNames.length > 0,
+    successStatus,
+  });
+
+  const result: DescribeEndpointResult = {
+    method: method.toUpperCase(),
+    path: resolvedPath,
+    ...(operation.operationId ? { operationId: operation.operationId } : {}),
+    ...(operation.summary ? { summary: operation.summary } : {}),
+    ...(operation.description ? { description: operation.description } : {}),
+    ...(operation.tags?.length ? { tags: operation.tags } : {}),
+    deprecated: operation.deprecated ?? false,
+    security: securityNames,
+    parameters: grouped,
+    ...(requestBody ? { requestBody } : {}),
+    responses,
+    testSnippet,
+  };
+
+  return decycleSchema(result) as DescribeEndpointResult;
+}
+
+export async function describeCompact(
+  specPath: string,
+  options?: { insecure?: boolean },
+): Promise<CompactEndpoint[]> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+  const paths = doc.paths ?? {};
+  const result: CompactEndpoint[] = [];
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    for (const method of ["get","post","put","patch","delete","head","options","trace"]) {
+      const op = (pathItem as any)?.[method] as OpenAPIV3.OperationObject | undefined;
+      if (!op) continue;
+      result.push({
+        method: method.toUpperCase(),
+        path,
+        ...(op.operationId ? { operationId: op.operationId } : {}),
+        ...(op.summary ? { summary: op.summary } : {}),
+        deprecated: op.deprecated ?? false,
+      });
+    }
+  }
+
+  return result;
+}

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

@@ -196,6 +196,26 @@ Use spec paths with \`{param}\` placeholders in the path for coverage to match:
 - Spec says \`GET /products/{id}\` → write \`GET: /products/1\` (hardcode the value)
 - Coverage scanner matches test paths against spec paths automatically
 
+### Suite variable isolation — IMPORTANT
+Each suite runs in its own variable scope. Captured variables (via \`capture:\`) do NOT propagate between suites.
+If multiple suites need auth, each suite must either:
+- Include its own login step with \`capture: auth_token\`
+- Or use \`auth_token\` from \`.env.yaml\` (pre-configured, no capture needed)
+
+Do NOT create a separate "setup" suite expecting other suites to use its captures.
+
+### ETag / Conditional Requests
+If-Match and If-None-Match require escaped quotes around the ETag value:
+\`\`\`yaml
+  - name: Update with ETag
+    PUT: /items/{{item_id}}
+    headers:
+      If-Match: "\\"{{etag}}\\""
+    json: { name: "updated" }
+    expect:
+      status: 200
+\`\`\`
+
 ### CRITICAL: Never mask server errors
 - If an endpoint returns 500 — do NOT change expect to \`status: 500\`. Keep \`status: 200\` and let the test fail.
 - A failing test = signal about an API bug. The goal is NOT "all tests green" but "tests reflect expected behavior".