@kirrosh/zond 0.20.0 → 0.22.0

package/src/core/generator/suite-generator.ts

@@ -28,6 +28,30 @@ function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
   });
 }
 
+/**
+ * For negative-smoke suites: replace path params with guaranteed-non-existent values.
+ * Picks a value that's syntactically valid for the param's type/format but very
+ * unlikely to match a real resource (zero-UUID, very large int, sentinel string).
+ */
+function getNonexistentSeed(schema: OpenAPIV3.SchemaObject | undefined): string {
+  if (!schema) return "nonexistent_id_zzzzzz";
+  if (schema.format === "uuid") return "00000000-0000-0000-0000-000000000000";
+  if (schema.type === "integer" || schema.type === "number") return "999999999";
+  return "nonexistent_id_zzzzzz";
+}
+
+function convertPathWithBadIds(path: string, ep: EndpointInfo): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = ep.parameters.find(p => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    return getNonexistentSeed(schema);
+  });
+}
+
+function endpointHasPathParams(ep: EndpointInfo): boolean {
+  return ep.parameters.some(p => p.in === "path");
+}
+
 function slugify(s: string): string {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
@@ -360,9 +384,11 @@ export function generateCrudSuite(
       });
     }
 
+    // T44: cleanup must run even if earlier assertions failed (tainted captures)
     const step: RawStep = {
       name: group.delete.operationId ?? `Delete ${group.resource.replace(/s$/, "")}`,
       DELETE: itemPath,
+      always: true,
       expect: {
         status: getExpectedStatus(group.delete),
       },
@@ -372,11 +398,12 @@ export function generateCrudSuite(
     }
     tests.push(step);
 
-    // 5. Verify deleted
+    // 5. Verify deleted — also always, so we confirm cleanup happened
     if (group.read) {
       tests.push({
         name: `Verify ${group.resource.replace(/s$/, "")} deleted`,
         GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+        always: true,
         expect: {
           status: 404,
         },
@@ -384,9 +411,13 @@ export function generateCrudSuite(
     }
   }
 
+  // T28: classify by cleanup behavior. A suite that owns a DELETE leaves the API
+  // in its starting state (ephemeral); without DELETE it leaves residual data.
+  const cleanupTag = group.delete ? "ephemeral" : "persistent-write";
+
   const suite: RawSuite = {
     name: `${group.resource}-crud`,
-    tags: ["crud"],
+    tags: ["crud", cleanupTag],
     fileStem: `crud-${slugify(group.resource)}`,
     base_url: "{{base_url}}",
     tests,
@@ -634,17 +665,20 @@ export function generateSuites(opts: {
   for (const [tag, tagEndpoints] of byTag) {
     const tagSlug = slugify(tag) || "api";
 
-    // GET endpoints → smoke suite (use seed values for path params — no capture context)
+    // GET endpoints → split into paramless (regular smoke) and path-param (negative+positive smoke)
     const getEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() === "GET");
-    if (getEndpoints.length > 0) {
-      const tests = getEndpoints.map(ep => {
+    const paramlessGets = getEndpoints.filter(ep => !endpointHasPathParams(ep));
+    const pathParamGets = getEndpoints.filter(ep => endpointHasPathParams(ep));
+
+    // Regular smoke: paramless GETs (e.g. list endpoints, health checks)
+    if (paramlessGets.length > 0) {
+      const tests = paramlessGets.map(ep => {
         const step = generateStep(ep, securitySchemes);
-        // Replace path param placeholders with seed values so the suite runs out of the box
         const seededPath = convertPathWithSeeds(ep.path, ep);
         (step as any)[ep.method.toUpperCase()] = seededPath;
         return step;
       });
-      const headers = getSuiteHeaders(getEndpoints, securitySchemes);
+      const headers = getSuiteHeaders(paramlessGets, securitySchemes);
 
       const suite: RawSuite = {
         name: `${tagSlug}-smoke`,
@@ -666,6 +700,71 @@ export function generateSuites(opts: {
       suites.push(suite);
     }
 
+    // Negative smoke: path-param GETs with guaranteed-bad IDs, expect 400/404/422
+    if (pathParamGets.length > 0) {
+      const tests = pathParamGets.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        (step as any)[ep.method.toUpperCase()] = convertPathWithBadIds(ep.path, ep);
+        // Negative path: resource doesn't exist. Drop body assertions (response shape varies).
+        step.expect = { status: [400, 404, 422] };
+        return step;
+      });
+      const headers = getSuiteHeaders(pathParamGets, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke-negative`,
+        tags: ["smoke", "negative"],
+        fileStem: `smoke-${tagSlug}-negative`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
+    // Positive smoke: path-param GETs with {{var}} placeholders + skip_if for unset env
+    if (pathParamGets.length > 0) {
+      const tests = pathParamGets.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        // Path stays as {{param}} so user-provided env values flow in
+        // Pick the first path param for skip_if guard (the resource ID)
+        const firstPathParam = ep.parameters.find(p => p.in === "path");
+        if (firstPathParam) {
+          step.skip_if = `{{${firstPathParam.name}}} ==`;
+        }
+        return step;
+      });
+      const headers = getSuiteHeaders(pathParamGets, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke-positive`,
+        tags: ["smoke", "positive", "needs-id"],
+        fileStem: `smoke-${tagSlug}-positive`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
     // Non-GET endpoints: split reset/system endpoints out of smoke-unsafe
     const nonGetEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
     const resetEndpoints = nonGetEndpoints.filter(ep => RESET_PATH_RE.test(ep.path));

package/src/core/meta/types.ts

@@ -12,8 +12,6 @@ export interface ZondMeta {
   zondVersion: string;
   /** ISO timestamp of last sync/generate */
   lastSyncedAt: string;
-  /** Spec URL or file path used for last generation */
-  specUrl: string;
   /** SHA-256 hex of spec content at time of last generation */
   specHash: string;
   /** Per-file metadata, keyed by filename (e.g. "smoke-users.yaml") */

package/src/core/parser/schema.ts

@@ -92,7 +92,7 @@ const AssertionRuleSchemaInner: z.ZodType<AssertionRule> = z.preprocess(
   },
   z.object({
     capture: z.string().optional(),
-    type: z.enum(["string", "integer", "number", "boolean", "array", "object"]).optional(),
+    type: z.enum(["string", "integer", "number", "boolean", "array", "object", "null"]).optional(),
     equals: z.unknown().optional(),
     not_equals: z.unknown().optional(),
     contains: z.string().optional(),
@@ -184,6 +184,7 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
     retry_until: RetryUntilSchema.optional(),
     for_each: ForEachSchema.optional(),
     set: z.record(z.string(), z.unknown()).optional(),
+    always: z.boolean().optional(),
   }),
 ) as z.ZodType<TestStep>;
 
@@ -220,6 +221,7 @@ const TestSuiteSchema = z.preprocess(
     tags: z.array(z.string()).optional(),
     base_url: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
+    parameterize: z.record(z.string(), z.array(z.unknown()).min(1)).optional(),
     config: SuiteConfigSchema,
     tests: z.array(TestStepSchema).min(1),
   }),

package/src/core/parser/types.ts

@@ -2,7 +2,7 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
 export interface AssertionRule {
   capture?: string;
-  type?: "string" | "integer" | "number" | "boolean" | "array" | "object";
+  type?: "string" | "integer" | "number" | "boolean" | "array" | "object" | "null";
   equals?: unknown;
   not_equals?: unknown;
   contains?: string;
@@ -63,6 +63,12 @@ export interface TestStep {
   retry_until?: RetryUntil;
   for_each?: ForEach;
   set?: Record<string, unknown>;
+  /**
+   * Run this step even when prior steps in the suite have failed assertions
+   * (so their captures are "tainted"). Designed for cleanup steps. Still
+   * skips if a referenced capture is genuinely missing from a response.
+   */
+  always?: boolean;
 }
 
 export interface SuiteConfig {
@@ -81,6 +87,9 @@ export interface TestSuite {
   tags?: string[];
   base_url?: string;
   headers?: Record<string, string>;
+  /** Cross-product parameterisation: each key contributes one variable
+   *  binding per array entry. Suite body runs once per combination. */
+  parameterize?: Record<string, unknown[]>;
   config: SuiteConfig;
   tests: TestStep[];
   /** Absolute path to the source file, set by yaml-parser */

package/src/core/parser/variables.ts

@@ -16,6 +16,23 @@ function randomChars(len: number): string {
   return result;
 }
 
+function lowerChars(len: number): string {
+  let result = "";
+  for (let i = 0; i < len; i++) {
+    const idx = Math.floor(Math.random() * 36);
+    result += CHARS[idx]!.toLowerCase();
+  }
+  return result;
+}
+
+function randomOctet(): number {
+  return Math.floor(Math.random() * 254) + 1;
+}
+
+function randomDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
 export const GENERATORS: Record<string, () => string | number> = {
   "$uuid": () => crypto.randomUUID(),
   "$timestamp": () => Math.floor(Date.now() / 1000),
@@ -24,10 +41,38 @@ export const GENERATORS: Record<string, () => string | number> = {
   "$randomEmail": () => `${randomChars(8).toLowerCase()}@test.com`,
   "$randomInt": () => Math.floor(Math.random() * 10000),
   "$randomString": () => randomChars(8),
+  "$randomUrl": () => `https://example-${lowerChars(8)}.com/path`,
+  "$randomFqdn": () => `test-${lowerChars(8)}.example.com`,
+  "$randomIpv4": () => `10.${randomOctet()}.${randomOctet()}.${randomOctet()}`,
+  "$randomDate": randomDate,
+  "$randomIsoDate": () => new Date().toISOString(),
 };
 
 const VAR_PATTERN = /\{\{(.+?)\}\}/g;
 
+/**
+ * Suggest a known generator close to the misspelled name.
+ * Case-insensitive prefix match first, then case-insensitive exact match.
+ */
+function suggestGenerator(name: string): string | undefined {
+  const lower = name.toLowerCase();
+  const known = Object.keys(GENERATORS);
+  // Case-insensitive exact (catches case-only typos like $randomfqdn → $randomFqdn)
+  const ciExact = known.find((k) => k.toLowerCase() === lower);
+  if (ciExact) return ciExact;
+  // Prefix match
+  return known.find((k) => k.toLowerCase().startsWith(lower.slice(0, 6)));
+}
+
+function unknownGeneratorError(key: string): Error {
+  const suggestion = suggestGenerator(key);
+  const hint = suggestion ? ` (did you mean ${suggestion}?)` : "";
+  const available = Object.keys(GENERATORS).join(", ");
+  return new Error(
+    `Unknown generator: {{${key}}}${hint}. Available: ${available}`,
+  );
+}
+
 export function substituteString(template: string, vars: Record<string, unknown>): unknown {
   // If entire string is a single {{var}}, return raw value (number stays number)
   const singleMatch = template.match(/^\{\{([^{}]+)\}\}$/);
@@ -35,6 +80,7 @@ export function substituteString(template: string, vars: Record<string, unknown>
     const key = singleMatch[1]!;
     if (key in vars) return vars[key];
     if (key in GENERATORS) return GENERATORS[key]!();
+    if (key.startsWith("$")) throw unknownGeneratorError(key);
     return template;
   }
 
@@ -42,6 +88,7 @@ export function substituteString(template: string, vars: Record<string, unknown>
   return template.replace(new RegExp(VAR_PATTERN.source, "g"), (_, key: string) => {
     if (key in vars) return String(vars[key]);
     if (key in GENERATORS) return String(GENERATORS[key]!());
+    if (key.startsWith("$")) throw unknownGeneratorError(key);
     return `{{${key}}}`;
   });
 }
@@ -110,7 +157,7 @@ export function extractVariableReferences(step: TestStep): string[] {
   return [...refs];
 }
 
-async function loadEnvFile(filePath: string): Promise<Record<string, string> | null> {
+export async function loadEnvFile(filePath: string): Promise<Record<string, string> | null> {
   try {
     const text = await Bun.file(filePath).text();
     const parsed = Bun.YAML.parse(text);
@@ -154,5 +201,46 @@ export async function loadEnvironment(envName?: string, searchDir: string = ".")
   const fileVars = await loadEnvFile(`${searchDir}/${fileName}`);
   const parentFileVars = await loadEnvFile(`${dirname(searchDir)}/${fileName}`);
 
-  return { ...parentFileVars, ...fileVars };
+  const merged = { ...parentFileVars, ...fileVars };
+  // Strip reserved meta keys so they don't leak into variable substitution
+  for (const key of META_KEYS) {
+    delete merged[key];
+  }
+  return merged;
+}
+
+const META_KEYS = ["rateLimit"] as const;
+
+export interface EnvMeta {
+  rateLimit?: number;
+}
+
+async function readEnvMetaFile(filePath: string): Promise<EnvMeta | null> {
+  try {
+    const text = await Bun.file(filePath).text();
+    const parsed = Bun.YAML.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    const obj = parsed as Record<string, unknown>;
+    const meta: EnvMeta = {};
+    if ("rateLimit" in obj) {
+      const v = obj.rateLimit;
+      if (typeof v === "number" && Number.isFinite(v) && v > 0) {
+        meta.rateLimit = v;
+      } else if (typeof v === "string") {
+        const n = Number.parseFloat(v);
+        if (Number.isFinite(n) && n > 0) meta.rateLimit = n;
+      }
+    }
+    return meta;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function loadEnvMeta(envName?: string, searchDir: string = "."): Promise<EnvMeta> {
+  const fileName = envName ? `.env.${envName}.yaml` : ".env.yaml";
+  const parent = await readEnvMetaFile(`${dirname(searchDir)}/${fileName}`);
+  const own = await readEnvMetaFile(`${searchDir}/${fileName}`);
+  return { ...(parent ?? {}), ...(own ?? {}) };
 }

package/src/core/parser/yaml-parser.ts

@@ -1,8 +1,46 @@
 import { Glob } from "bun";
 import { resolve } from "node:path";
+import YAML from "yaml";
 import { validateSuite } from "./schema.ts";
 import type { TestSuite } from "./types.ts";
 
+/** Convert a 0-based byte offset into a 1-based (line, col) position. */
+function offsetToLineCol(text: string, offset: number): { line: number; col: number } {
+  let line = 1;
+  let col = 1;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text.charCodeAt(i) === 0x0a) {
+      line++;
+      col = 1;
+    } else {
+      col++;
+    }
+  }
+  return { line, col };
+}
+
+/**
+ * Format a YAML parse error as `file:line:col: <reason>` plus a snippet with
+ * a column pointer. Bun.YAML's SyntaxError exposes JS stack coordinates, not
+ * YAML positions, so on parse failure we re-parse with eemeli/yaml (which
+ * provides accurate `linePos`) just for diagnostics.
+ *
+ * Exported for tests.
+ */
+export function formatYamlParseError(filePath: string, text: string, primary: Error): Error {
+  const doc = YAML.parseDocument(text);
+  const e = doc.errors[0];
+  if (e?.linePos?.[0]) {
+    const { line, col } = e.linePos[0];
+    // eemeli's message reads "<reason> at line X, column Y:\n\n<snippet>".
+    // Strip the "at line ..." part since we surface line:col in the prefix.
+    const cleaned = e.message.replace(/\s+at line \d+, column \d+:/, ":");
+    return new Error(`Invalid YAML in ${filePath}:${line}:${col}: ${cleaned}`);
+  }
+  // eemeli accepted but Bun rejected — fall back to original message.
+  return new Error(`Invalid YAML in ${filePath}: ${primary.message}`);
+}
+
 export async function parseFile(filePath: string): Promise<TestSuite> {
   let text: string;
   try {
@@ -11,11 +49,22 @@ export async function parseFile(filePath: string): Promise<TestSuite> {
     throw new Error(`Failed to read file ${filePath}: ${(err as Error).message}`);
   }
 
+  // Both Bun.YAML and eemeli/yaml accept NUL bytes silently, but they corrupt
+  // downstream consumers (sqlite TEXT, JSON, terminals). Surface explicitly.
+  const nulIdx = text.indexOf("\x00");
+  if (nulIdx >= 0) {
+    const { line, col } = offsetToLineCol(text, nulIdx);
+    throw new Error(
+      `Invalid YAML in ${filePath}:${line}:${col}: NUL byte (\\x00) in source — ` +
+      `if you need a NUL in a request body, use the {{$nullByte}} generator instead of inlining the byte`
+    );
+  }
+
   let raw: unknown;
   try {
     raw = Bun.YAML.parse(text);
   } catch (err) {
-    throw new Error(`Invalid YAML in ${filePath}: ${(err as Error).message}`);
+    throw formatYamlParseError(filePath, text, err as Error);
   }
 
   try {

package/src/core/probe/method-probe.ts

@@ -0,0 +1,197 @@
+/**
+ * HTTP method completeness probe (T48).
+ *
+ * Goal: catch the class of bugs where an API responds to *unsupported* HTTP
+ * methods with anything other than 405 / 404. A 500 here means an unhandled
+ * exception in the routing layer; a 200/201 means a forgotten or shadowed
+ * route; both are bug candidates.
+ *
+ * For every path declared in the spec, we look at which of {GET, POST, PUT,
+ * PATCH, DELETE} are *not* declared and emit one probe step per missing
+ * method. Each probe expects status in [404, 405, 401, 403] — anything else
+ * (notably 5xx, 200, 201) is a regular test failure surfaced via the
+ * existing runner / reporter / `zond db diagnose` flow.
+ *
+ * The probes are deterministic — same spec → same suites — so the generated
+ * YAML can be committed as a regression test.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
+import type { RawSuite, RawStep } from "../generator/serializer.ts";
+
+// ──────────────────────────────────────────────
+// Constants
+// ──────────────────────────────────────────────
+
+const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+type Method = (typeof ALL_METHODS)[number];
+
+/** Statuses we accept on a *missing* method. 405 is canonical, 404 is a
+ *  common fallback (path not registered for that method), 401/403 are
+ *  acceptable when auth is checked before routing. Anything else — notably
+ *  5xx (unhandled), 200/201 (silent acceptance) — is a probe failure. */
+const ACCEPTABLE_STATUSES = [401, 403, 404, 405];
+
+// ──────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────
+
+export interface MethodProbeOptions {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+}
+
+export interface MethodProbeResult {
+  suites: RawSuite[];
+  /** Number of distinct paths probed. */
+  probedPaths: number;
+  /** Paths skipped because every method in {GET,POST,PUT,PATCH,DELETE} is declared. */
+  skippedPaths: number;
+  /** Total generated probe steps. */
+  totalProbes: number;
+}
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+function convertPath(path: string): string {
+  return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+}
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function pathStem(path: string): string {
+  const cleaned = path
+    .replace(/\{[^}]+\}/g, "by-id")
+    .replace(/^\//, "")
+    .replace(/\//g, "-");
+  return slugify(cleaned) || "root";
+}
+
+/** Replace path params with valid-shape placeholders so the request can
+ *  reach the routing layer without being rejected purely on path syntax. */
+function pathWithPlaceholders(
+  path: string,
+  parameters: OpenAPIV3.ParameterObject[],
+): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = parameters.find((p) => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    if (schema?.format === "uuid") return "00000000-0000-0000-0000-000000000000";
+    if (schema?.type === "integer" || schema?.type === "number") return "999999999";
+    return "nonexistent-zzzzz";
+  });
+}
+
+function getAuthHeaders(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+): Record<string, string> | undefined {
+  if (ep.security.length === 0) return undefined;
+  for (const secName of ep.security) {
+    const scheme = schemes.find((s) => s.name === secName);
+    if (!scheme) continue;
+    if (scheme.type === "http") {
+      if (scheme.scheme === "bearer" || !scheme.scheme) {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
+      if (scheme.scheme === "basic") {
+        return { Authorization: "Basic {{auth_token}}" };
+      }
+    }
+    if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
+      if (scheme.apiKeyName === "Authorization") {
+        return { Authorization: "Bearer {{auth_token}}" };
+      }
+      return { [scheme.apiKeyName]: "{{api_key}}" };
+    }
+  }
+  return undefined;
+}
+
+interface PathBucket {
+  path: string;
+  /** Methods declared on this path, normalized to upper-case. */
+  declared: Set<string>;
+  /** A representative endpoint we can borrow auth/path-param shape from. */
+  sample: EndpointInfo;
+}
+
+function bucketByPath(endpoints: EndpointInfo[]): PathBucket[] {
+  const map = new Map<string, PathBucket>();
+  for (const ep of endpoints) {
+    if (ep.deprecated) continue;
+    let bucket = map.get(ep.path);
+    if (!bucket) {
+      bucket = { path: ep.path, declared: new Set(), sample: ep };
+      map.set(ep.path, bucket);
+    }
+    bucket.declared.add(ep.method.toUpperCase());
+  }
+  return Array.from(map.values());
+}
+
+// ──────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────
+
+export function generateMethodProbes(opts: MethodProbeOptions): MethodProbeResult {
+  const { endpoints, securitySchemes } = opts;
+  const methodSet: readonly Method[] = ALL_METHODS;
+
+  const buckets = bucketByPath(endpoints);
+  const suites: RawSuite[] = [];
+  let probedPaths = 0;
+  let skippedPaths = 0;
+  let totalProbes = 0;
+
+  for (const bucket of buckets) {
+    const missing = methodSet.filter((m) => !bucket.declared.has(m));
+    if (missing.length === 0) {
+      skippedPaths++;
+      continue;
+    }
+
+    const concretePath = pathWithPlaceholders(
+      bucket.path,
+      bucket.sample.parameters,
+    );
+    const headers = getAuthHeaders(bucket.sample, securitySchemes);
+
+    const steps: RawStep[] = missing.map((method) => {
+      const step: RawStep = {
+        name: `${method} ${bucket.path} — undeclared method must reject (no 5xx, no 2xx)`,
+        [method]: convertPath(concretePath),
+        expect: { status: ACCEPTABLE_STATUSES },
+      };
+      // Body-bearing methods on an undeclared route — send a minimal valid
+      // JSON object to provoke any body-parsing path while the router is
+      // still expected to reject the method first.
+      if (method === "POST" || method === "PUT" || method === "PATCH") {
+        (step as any).json = {};
+      }
+      return step;
+    });
+
+    probedPaths++;
+    totalProbes += steps.length;
+
+    const stem = pathStem(bucket.path);
+    suites.push({
+      name: `probe methods ${bucket.path}`,
+      tags: ["probe-methods", "negative-method", "no-5xx", "smoke"],
+      fileStem: `probe-methods-${stem}`,
+      base_url: "{{base_url}}",
+      ...(headers ? { headers } : {}),
+      tests: steps,
+    });
+  }
+
+  return { suites, probedPaths, skippedPaths, totalProbes };
+}