@kirrosh/zond 0.21.0 → 0.22.0

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 };
+}