@kirrosh/zond 0.26.1 → 0.27.0

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

@@ -1,164 +0,0 @@
-/**
- * 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";
-import { pathWithByAliases, getAuthHeaders } from "./shared.ts";
-import {
-  ALL_METHODS,
-  ACCEPTABLE_UNSUPPORTED_STATUSES,
-  bucketEndpointsByPath,
-  pathWithMethodPlaceholders,
-  type Method,
-} from "./method-shared.ts";
-
-// 405-or-equivalent statuses for an *undeclared* method probe. ARV-2
-// (m-15) extracted this list to method-shared.ts so the live
-// `unsupported_method` check stays in lock-step with the offline probe.
-const ACCEPTABLE_STATUSES = [...ACCEPTABLE_UNSUPPORTED_STATUSES];
-
-// ──────────────────────────────────────────────
-// 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 {
-  // TASK-159 (m-9 P3): preserve placeholder name (`by-org`, `by-proj`)
-  // instead of collapsing every `{x}` to a generic `by-id`.
-  const cleaned = pathWithByAliases(path)
-    .replace(/^\//, "")
-    .replace(/\//g, "-");
-  return slugify(cleaned) || "root";
-}
-
-// pathWithPlaceholders + bucketByPath moved to ./method-shared.ts for
-// reuse by the live `unsupported_method` check (m-15 ARV-2).
-const pathWithPlaceholders = pathWithMethodPlaceholders;
-const bucketByPath = (endpoints: EndpointInfo[]): Array<{
-  path: string;
-  declared: Set<string>;
-  sample: EndpointInfo;
-}> => Array.from(bucketEndpointsByPath(endpoints).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) => {
-      // ARV-179: OPTIONS on an undeclared path is legitimately handled
-      // by most stacks (CORS preflight, 200/204 with Allow header). Let
-      // the probe accept 2xx for OPTIONS only; everything else keeps
-      // the strict "no 2xx, no 5xx" expectation.
-      const acceptable = method === "OPTIONS"
-        ? [200, 204, ...ACCEPTABLE_STATUSES]
-        : ACCEPTABLE_STATUSES;
-      const expectLabel = method === "OPTIONS"
-        ? `${method} ${bucket.path} — undeclared method must not 5xx (OPTIONS may legitimately succeed)`
-        : `${method} ${bucket.path} — undeclared method must reject (no 5xx, no 2xx)`;
-      const step: RawStep = {
-        name: expectLabel,
-        source: {
-          generator: "method-probe",
-          endpoint: `${method} ${bucket.path}`,
-          response_branch: acceptable.map(String).join("|"),
-        },
-        [method]: convertPath(concretePath),
-        expect: { status: acceptable },
-      };
-      // 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"],
-      source: {
-        type: "probe-suite",
-        generator: "method-probe",
-        endpoint: bucket.path,
-      },
-      fileStem: `probe-methods-${stem}`,
-      base_url: "{{base_url}}",
-      ...(headers ? { headers } : {}),
-      tests: steps,
-    });
-  }
-
-  return { suites, probedPaths, skippedPaths, totalProbes };
-}

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

@@ -1,69 +0,0 @@
-/**
- * Shared bits between the offline `method-probe` (which emits YAML
- * suites) and the live `unsupported_method` check from `core/checks`
- * (m-15 ARV-2). Both ask the same question — "which HTTP methods aren't
- * declared on this path?" — so the constants and helpers live here so
- * the two stay in lock-step (ARV-2 AC #4).
- */
-import type { OpenAPIV3 } from "openapi-types";
-import type { EndpointInfo } from "../generator/types.ts";
-
-/** ARV-179: full HTTP method complement used for `unsupported_method`
- *  enumeration. Matches schemathesis V4 `DEFAULT_UNEXPECTED_METHODS`
- *  minus the WebDAV-style `query` (not a REST norm) and `CONNECT`
- *  (irrelevant to API routing). `HEAD` is intentionally excluded
- *  because most stacks auto-derive it from `GET`, so a 2xx response is
- *  expected behaviour rather than a leak. */
-export const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE"] as const;
-export type Method = (typeof ALL_METHODS)[number];
-
-/** Statuses we accept for an *undeclared* method on a path. 405 is
- *  canonical, 404 is a common fallback (path not registered for that
- *  method), 401/403 are acceptable when auth is checked before routing. */
-export const ACCEPTABLE_UNSUPPORTED_STATUSES = [401, 403, 404, 405] as const;
-
-/** ARV-179: OPTIONS is special — it's legitimately implemented by most
- *  stacks for CORS preflight and may legitimately return 2xx with
- *  `Allow`/`Access-Control-*` headers. A 2xx OPTIONS on an undeclared
- *  path is the spec-compliant outcome, not a finding. Use this helper
- *  in both the offline probe and the live check to keep the policy in
- *  one place. */
-export function isPermissibleOptionsResponse(method: string, status: number): boolean {
-  return method.toUpperCase() === "OPTIONS" && status >= 200 && status < 300;
-}
-
-/**
- * Replace `{name}` segments with valid-shape placeholders so the
- * request can reach the routing layer without being rejected purely on
- * path syntax. Used by both the offline probe and the live check.
- */
-export function pathWithMethodPlaceholders(
-  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";
-  });
-}
-
-export function bucketEndpointsByPath(endpoints: EndpointInfo[]): Map<string, {
-  path: string;
-  declared: Set<string>;
-  sample: EndpointInfo;
-}> {
-  const map = new Map<string, { path: string; declared: Set<string>; sample: EndpointInfo }>();
-  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 map;
-}