@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/parser/env-interpolation.ts

@@ -0,0 +1,104 @@
+/**
+ * `${VAR}` / `${VAR:-default}` substitution for `.env.yaml` (TASK-169, m-10).
+ *
+ * Lets a workspace commit `.env.yaml` without bare secrets:
+ *
+ *     auth_token: "${MYAPI_AUTH_TOKEN}"
+ *     base_url:   "${MYAPI_BASE_URL:-https://api.example.com}"
+ *
+ * Rules:
+ *   - `${VAR}`           → process.env.VAR (throws if missing).
+ *   - `${VAR:-default}`  → process.env.VAR ?? default. The default may
+ *     contain `:` (everything after `:-` up to the closing `}` is the
+ *     default).
+ *   - `\${LITERAL}`      → literal `${LITERAL}` (the backslash is
+ *     stripped). Matches the `dotenv-expand` / docker-compose convention.
+ *   - One level of resolution only — values pulled from env are NOT
+ *     re-scanned for further `${...}` (cycle-risk).
+ *   - Variable names matching /TOKEN|SECRET|PASSWORD|KEY|DSN/i are NOT
+ *     auto-registered with the redaction registry. Auto-registration is
+ *     opt-in via `@secret:` (TASK-170). We do print a one-line warning
+ *     suggesting the user mark them as a secret, but only the first time.
+ */
+
+const ENV_REF_RE = /(\\?)\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+const SUSPICIOUS_NAME_RE = /TOKEN|SECRET|PASSWORD|API_KEY|^KEY$|_KEY$|DSN/i;
+
+export interface EnvInterpolationContext {
+  /** Absolute path of the file we're resolving — used for error messages. */
+  filePath: string;
+  /** YAML key whose value contains the reference — used for error messages. */
+  key: string;
+  /** Source of variables; defaults to `process.env`. Override in tests. */
+  env?: Record<string, string | undefined>;
+  /** Sink for human-facing warnings. Default: stderr write. */
+  warn?: (msg: string) => void;
+}
+
+/** Module-level set of variable names we've already warned about, so the
+ *  same `${MYAPI_AUTH_TOKEN}` reference doesn't yell once per env file. */
+const warned = new Set<string>();
+
+export function _resetEnvInterpolationWarnings(): void {
+  warned.clear();
+}
+
+/**
+ * Substitute every `${VAR}` / `${VAR:-default}` in `text`. Returns the
+ * fully-resolved string. Throws `Error` when an unresolved reference has
+ * no default.
+ */
+export function interpolateEnvRefs(text: string, ctx: EnvInterpolationContext): string {
+  if (typeof text !== "string" || text.length === 0) return text;
+  if (text.indexOf("${") === -1 && text.indexOf("\\$") === -1) return text;
+  const env = ctx.env ?? (process.env as Record<string, string | undefined>);
+  const warn = ctx.warn ?? ((m: string) => process.stderr.write(m + "\n"));
+
+  return text.replace(ENV_REF_RE, (full, escape: string, name: string, def: string | undefined) => {
+    if (escape === "\\") {
+      // Escaped reference → strip the backslash, keep the literal.
+      return full.slice(1);
+    }
+    const value = env[name];
+    if (value === undefined || value === "") {
+      if (def !== undefined) {
+        return def;
+      }
+      throw new Error(
+        `Environment variable \${${name}} is not set (referenced from "${ctx.filePath}", key "${ctx.key}"). ` +
+        `Provide it via your shell, CI secret, or use the \${${name}:-<default>} form to give it a fallback.`,
+      );
+    }
+    if (SUSPICIOUS_NAME_RE.test(name) && !warned.has(name)) {
+      warned.add(name);
+      warn(
+        `[zond] ${ctx.filePath}: variable \${${name}} looks like a secret. ` +
+        `Consider mapping it through @secret:${ctx.key} (TASK-170) so it is redacted in artifacts.`,
+      );
+    }
+    return value;
+  });
+}
+
+/**
+ * Apply interpolation to every string value in a flat env object. Other
+ * value types (numbers, booleans, nulls coming back from YAML) are
+ * stringified untouched, matching the existing loader behaviour.
+ */
+export function interpolateEnvObject(
+  obj: Record<string, unknown>,
+  filePath: string,
+  env?: Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") {
+      out[k] = interpolateEnvRefs(v, { filePath, key: k, env });
+    } else {
+      out[k] = String(v);
+    }
+  }
+  return out;
+}
+
+const SUSPICIOUS_ENV_NAME_RE = SUSPICIOUS_NAME_RE;

package/src/core/parser/filter.ts

@@ -1,4 +1,6 @@
 import type { TestSuite } from "./types.ts";
+import { compileOperationFilter } from "../selectors/operation-filter.ts";
+import type { EndpointInfo } from "../generator/types.ts";
 
 /**
  * Filter suites by tags (OR logic, case-insensitive).
@@ -38,3 +40,58 @@ export function filterSuitesByMethod(suites: TestSuite[], method: string): TestS
   }));
   return filtered.filter(s => s.tests.length > 0);
 }
+
+export interface SuiteFilterResult {
+  suites: TestSuite[];
+  errors: string[];
+}
+
+/**
+ * ARV-25: parity with `zond generate`/`zond checks run` — apply the unified
+ * `--include`/`--exclude` selector grammar (path/method/tag/operation-id)
+ * to a list of test suites. Step-level selectors (path, method, operation-id)
+ * filter steps within a suite; suite-level selectors (tag) borrow each
+ * step's parent suite tags. A suite drops out once it has no steps left.
+ *
+ * Reuses `compileOperationFilter` so semantics match generate/checks 1:1
+ * (multiple --include combine with OR; --exclude evaluated after includes).
+ *
+ * `operation-id` matches against `step.source?.endpoint` ("METHOD /path"),
+ * which is what the generator records; tests authored manually without
+ * `source.endpoint` simply never match operation-id selectors.
+ */
+export function filterSuitesByOperationFilter(
+  suites: TestSuite[],
+  includes: string[],
+  excludes: string[],
+): SuiteFilterResult {
+  if (includes.length === 0 && excludes.length === 0) {
+    return { suites, errors: [] };
+  }
+  const compiled = compileOperationFilter({ includes, excludes });
+  if (compiled.errors.length > 0) {
+    return { suites: [], errors: compiled.errors };
+  }
+  const filtered = suites.map(suite => ({
+    ...suite,
+    tests: suite.tests.filter(step => compiled.filter(stepToEndpoint(suite, step))),
+  }));
+  return { suites: filtered.filter(s => s.tests.length > 0), errors: [] };
+}
+
+function stepToEndpoint(suite: TestSuite, step: TestSuite["tests"][number]): EndpointInfo {
+  const sourceEndpoint = typeof step.source?.endpoint === "string" ? step.source.endpoint : undefined;
+  return {
+    path: step.path,
+    method: step.method,
+    operationId: sourceEndpoint,
+    summary: undefined,
+    tags: suite.tags ?? [],
+    parameters: [],
+    requestBodySchema: undefined,
+    requestBodyContentType: undefined,
+    responseContentTypes: [],
+    responses: [],
+    security: [],
+  };
+}

package/src/core/parser/schema.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
-import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach, MultipartField } from "./types.ts";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach, MultipartField, SourceMetadata } from "./types.ts";
 
-const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+// ARV-223 (R16/F28): include OPTIONS / HEAD / TRACE so probe-method generated
+// suites (which emit one step per missing-method per path) parse and run.
+// Without this, `zond probe static --emit-tests → zond run` breaks end-to-end
+// on every API where these methods aren't already declared (= almost always).
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE"] as const;
 
 function extractMethodAndPath(raw: unknown): unknown {
   if (typeof raw !== "object" || raw === null) return raw;
@@ -92,7 +96,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(),
@@ -120,6 +124,44 @@ const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   (val) => {
     if (typeof val !== "object" || val === null) return val;
     const obj = val as Record<string, unknown>;
+    // Reject `expect.capture: {...}` — non-canonical syntax some users
+    // reach for. zond captures live INSIDE body-rules
+    // (`body: { "path.to.field": { capture: var_name } }`); a top-level
+    // `capture:` block inside `expect:` is silently dropped, leaving the
+    // test green with no captured values. Throw with a clear pointer.
+    // (TASK-247)
+    if ("capture" in obj && typeof obj.capture === "object" && obj.capture !== null && !Array.isArray(obj.capture)) {
+      throw new Error(
+        `'expect.capture: {...}' is not a valid step shape. Captures are defined per-field: ` +
+        `\`expect.body: { "<path>": { capture: <var_name> } }\`. ` +
+        `Top-level 'capture' inside 'expect' is silently ignored — the test would pass with no captured values.`,
+      );
+    }
+    // expect.status: spot-message for common wrong shapes.
+    // Schema accepts `number | number[]`. Users reaching from other tools often
+    // write `oneOf: [...]`, `any: [...]`, a string `"200"`, or an array
+    // containing strings. The raw zod-issue path (`tests.N.expect.status.0`)
+    // is hard to read — surface a single-line hint here. (TASK-249, feedback-13#F1)
+    if ("status" in obj && obj.status !== undefined && obj.status !== null) {
+      const s = obj.status;
+      const STATUS_HINT =
+        "expect.status: use a number (200), an array of numbers ([200, 404]), or omit. " +
+        "oneOf/any/anyOf are not supported.";
+      if (typeof s === "object" && !Array.isArray(s)) {
+        const keys = Object.keys(s as Record<string, unknown>);
+        const wrong = keys.find((k) => ["oneOf", "anyOf", "any", "in", "one_of"].includes(k));
+        if (wrong) {
+          throw new Error(`'expect.status' got '${wrong}: [...]' — ${STATUS_HINT}`);
+        }
+        throw new Error(`'expect.status' got an object — ${STATUS_HINT}`);
+      }
+      if (typeof s === "string") {
+        throw new Error(`'expect.status' got string "${s}" — ${STATUS_HINT}`);
+      }
+      if (Array.isArray(s) && s.some((v) => typeof v !== "number")) {
+        throw new Error(`'expect.status' array must contain only numbers — ${STATUS_HINT}`);
+      }
+    }
     // body: null → remove it
     if (obj.body === null) {
       const { body: _, ...rest } = obj;
@@ -158,12 +200,57 @@ const MultipartFileFieldSchema = z.object({
 
 const MultipartFieldSchema: z.ZodType<MultipartField> = z.union([z.string(), MultipartFileFieldSchema]);
 
+// Provenance metadata: passthrough — все поля optional, неизвестные пропускаем без warning
+const SourceMetadataSchema: z.ZodType<SourceMetadata> = z.object({
+  type: z.enum(["openapi-generated", "manual", "probe-suite"]).optional(),
+  spec: z.string().optional(),
+  generator: z.string().optional(),
+  generated_at: z.string().optional(),
+  endpoint: z.string().optional(),
+  response_branch: z.string().optional(),
+  schema_pointer: z.string().optional(),
+}).passthrough() as z.ZodType<SourceMetadata>;
+
+const KNOWN_STEP_KEYS = new Set([
+  "name", "source", "method", "path", "headers",
+  "json", "form", "multipart", "query", "expect",
+  "skip_if", "retry_until", "for_each", "set", "always",
+  // raw HTTP method keys are folded into method/path by extractMethodAndPath
+  ...HTTP_METHODS,
+]);
+
+// Common typo / wrong-name body keys we detect explicitly to emit an
+// actionable error instead of silently dropping. Real APIs reject the empty
+// POST that follows, but the user spends 10+ minutes debugging — this hint
+// turns it into a one-line fix. (TASK-244)
+const BODY_KEY_HINTS: Record<string, string> = {
+  body: "json (for application/json), form (urlencoded), or multipart (file upload)",
+  data: "json (for application/json) or form (urlencoded)",
+  payload: "json",
+  // TASK-257: previous hint pointed only at `form:` which is x-www-form-urlencoded
+  // and useless for file uploads. Surface `multipart:` explicitly so users with
+  // file-upload endpoints (file-upload endpoints, etc.) find it.
+  raw: "json for raw JSON, multipart: { field: { file: <path> } } for file upload, or form for urlencoded — raw bodies are not parsed",
+};
+
 const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
   (raw) => {
     const obj = extractMethodAndPath(raw);
-    // Make expect optional for set-only steps
     if (typeof obj === "object" && obj !== null) {
       const o = obj as Record<string, unknown>;
+
+      // Reject silently-dropped body-shaped keys with a clear suggestion.
+      for (const [bad, hint] of Object.entries(BODY_KEY_HINTS)) {
+        if (bad in o) {
+          const stepName = typeof o.name === "string" ? ` in step "${o.name}"` : "";
+          throw new Error(
+            `Unknown step key '${bad}'${stepName}. Did you mean '${hint}'? ` +
+            `(zond does not recognize '${bad}:' and would silently drop the body)`,
+          );
+        }
+      }
+
+      // Make expect optional for set-only steps
       if (o.set && !o.expect) {
         o.expect = {};
       }
@@ -172,6 +259,7 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
   },
   z.object({
     name: z.string(),
+    source: SourceMetadataSchema.optional(),
     method: z.enum(HTTP_METHODS),
     path: z.string(),
     headers: z.record(z.string(), z.string()).optional(),
@@ -184,6 +272,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>;
 
@@ -218,8 +307,10 @@ const TestSuiteSchema = z.preprocess(
     description: z.string().optional(),
     setup: z.boolean().optional(),
     tags: z.array(z.string()).optional(),
+    source: SourceMetadataSchema.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),
   }),
@@ -229,4 +320,40 @@ export function validateSuite(raw: unknown): TestSuite {
   return TestSuiteSchema.parse(raw) as TestSuite;
 }
 
-export { TestSuiteSchema, TestStepSchema, AssertionRuleSchema, ASSERTION_KEYS };
+/** Render a zod path array (`["tests", 0, "expect", "status"]`) as
+ * `tests[0].expect.status`. Numeric segments become bracket-indices, string
+ * segments dot-join. */
+function pathToHuman(path: ReadonlyArray<string | number>): string {
+  let out = "";
+  for (const seg of path) {
+    if (typeof seg === "number") out += `[${seg}]`;
+    else out += out ? `.${seg}` : seg;
+  }
+  return out || "(root)";
+}
+
+/**
+ * Format a {@link z.ZodError} as a compact, multi-line, human-readable list:
+ *
+ *   N validation issue(s):
+ *     <path>: <message>
+ *     ...
+ *
+ * The default `ZodError.message` is a JSON dump of the full issue list with
+ * internal field names (`_def`, deeply numeric paths, "Invalid input" prefix).
+ * The wrapper that callers used to surface ("Validation error in <file>:
+ * [{...}]") was unreadable for tester users — they had to mentally parse the
+ * stack to find the real path. (TASK-249)
+ */
+export function formatZodError(err: z.ZodError): string {
+  const lines = err.issues.map((i) => {
+    const path = pathToHuman(i.path as ReadonlyArray<string | number>);
+    // zod v4 messages are already readable; strip the redundant "Invalid input: "
+    // prefix that adds noise without info.
+    const msg = i.message.replace(/^Invalid input:\s*/, "");
+    return `  ${path}: ${msg}`;
+  });
+  const header = `${err.issues.length} validation issue${err.issues.length === 1 ? "" : "s"}:`;
+  return `${header}\n${lines.join("\n")}`;
+}
+

package/src/core/parser/types.ts

@@ -1,8 +1,8 @@
-export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "TRACE";
 
 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;
@@ -41,6 +41,22 @@ export interface ForEach {
   in: unknown;
 }
 
+/**
+ * Provenance metadata: «откуда этот test/suite». Optional, не участвует в
+ * matching/dedup/validation. Suite-level задаёт общие поля; step-level
+ * наследует через shallow merge `{ ...suite.source, ...step.source }`.
+ */
+export interface SourceMetadata {
+  type?: "openapi-generated" | "manual" | "probe-suite";
+  spec?: string;
+  generator?: string;
+  generated_at?: string;
+  endpoint?: string;
+  response_branch?: string;
+  schema_pointer?: string;
+  [key: string]: unknown;
+}
+
 export interface MultipartFileField {
   file: string;
   filename?: string;
@@ -51,6 +67,7 @@ export type MultipartField = string | MultipartFileField;
 
 export interface TestStep {
   name: string;
+  source?: SourceMetadata;
   method: HttpMethod;
   path: string;
   headers?: Record<string, string>;
@@ -63,6 +80,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 {
@@ -79,8 +102,12 @@ export interface TestSuite {
   /** If true, this suite runs before all regular suites and its captures are shared into their env */
   setup?: boolean;
   tags?: string[];
+  source?: SourceMetadata;
   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/yaml-parser.ts

@@ -1,9 +1,55 @@
 import { Glob } from "bun";
 import { resolve } from "node:path";
-import { validateSuite } from "./schema.ts";
+import YAML from "yaml";
+import { z } from "zod";
+import { validateSuite, formatZodError } from "./schema.ts";
 import type { TestSuite } from "./types.ts";
 
-export async function parseFile(filePath: string): Promise<TestSuite> {
+export interface ParseOptions {
+  /** Surface raw `ZodError.message` (the JSON-formatted issue stack) instead
+   * of the human-friendly summary. Useful for filing zod bugs / debugging the
+   * schema itself; default output is human-readable. (TASK-249) */
+  verbose?: boolean;
+}
+
+/** 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, opts: ParseOptions = {}): Promise<TestSuite> {
   let text: string;
   try {
     text = await Bun.file(filePath).text();
@@ -11,11 +57,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 {
@@ -23,22 +80,40 @@ export async function parseFile(filePath: string): Promise<TestSuite> {
     suite.filePath = resolve(filePath);
     return suite;
   } catch (err) {
+    if (err instanceof z.ZodError && !opts.verbose) {
+      throw new Error(`Validation error in ${filePath}:\n${formatZodError(err)}`);
+    }
     throw new Error(`Validation error in ${filePath}: ${(err as Error).message}`);
   }
 }
 
-export async function parseDirectory(dirPath: string): Promise<TestSuite[]> {
+/**
+ * Files that live alongside test suites but aren't suites themselves. The
+ * yaml-parser scans recursively from the workspace root, so picking these up
+ * would surface spurious "Validation error: missing field name" noise.
+ */
+function isNonSuiteYaml(file: string): boolean {
+  if (file.match(/\.env(\..+)?\.ya?ml$/)) return true;
+  // Workspace marker — present at the root of every zond workspace.
+  if (file === "zond.config.yml" || file === "zond.config.yaml") return true;
+  // Per-API artifact files written by `zond add api` / `zond refresh-api`.
+  // Match the basename so it works for files at any depth (apis/<name>/...).
+  const basename = file.split("/").pop() ?? file;
+  if (/^\.api-[a-z0-9-]+\.ya?ml$/i.test(basename)) return true;
+  return false;
+}
+
+export async function parseDirectory(dirPath: string, opts: ParseOptions = {}): Promise<TestSuite[]> {
   const glob = new Glob("**/*.{yaml,yml}");
   const suites: TestSuite[] = [];
 
   for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
-    // Skip environment files
-    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+    if (isNonSuiteYaml(file)) {
       continue;
     }
     const fullPath = `${dirPath}/${file}`;
     try {
-      suites.push(await parseFile(fullPath));
+      suites.push(await parseFile(fullPath, opts));
     } catch {
       // Skip files that fail to parse (e.g. invalid AI-generated YAML)
       // so one bad file doesn't block the entire directory
@@ -53,18 +128,18 @@ export interface ParseDirectoryResult {
   errors: { file: string; error: string }[];
 }
 
-export async function parseDirectorySafe(dirPath: string): Promise<ParseDirectoryResult> {
+export async function parseDirectorySafe(dirPath: string, opts: ParseOptions = {}): Promise<ParseDirectoryResult> {
   const glob = new Glob("**/*.{yaml,yml}");
   const suites: TestSuite[] = [];
   const errors: { file: string; error: string }[] = [];
 
   for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
-    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+    if (isNonSuiteYaml(file)) {
       continue;
     }
     const fullPath = `${dirPath}/${file}`;
     try {
-      suites.push(await parseFile(fullPath));
+      suites.push(await parseFile(fullPath, opts));
     } catch (err) {
       errors.push({ file, error: (err as Error).message });
     }
@@ -73,14 +148,34 @@ export async function parseDirectorySafe(dirPath: string): Promise<ParseDirector
   return { suites, errors };
 }
 
-export async function parse(path: string): Promise<TestSuite[]> {
+export async function parse(path: string, opts: ParseOptions = {}): Promise<TestSuite[]> {
   const file = Bun.file(path);
   const exists = await file.exists();
 
   if (exists) {
-    return [await parseFile(path)];
+    return [await parseFile(path, opts)];
   }
 
   // Not a file, try as directory
-  return parseDirectory(path);
+  return parseDirectory(path, opts);
+}
+
+/**
+ * Like {@link parse}, but never silently drops files. Returns both successfully
+ * parsed suites and per-file parse errors so callers (run, validate, tag-filter)
+ * can surface failures instead of pretending the file did not exist.
+ */
+export async function parseSafe(path: string, opts: ParseOptions = {}): Promise<ParseDirectoryResult> {
+  const file = Bun.file(path);
+  const exists = await file.exists();
+
+  if (exists) {
+    try {
+      return { suites: [await parseFile(path, opts)], errors: [] };
+    } catch (err) {
+      return { suites: [], errors: [{ file: path, error: (err as Error).message }] };
+    }
+  }
+
+  return parseDirectorySafe(path, opts);
 }

package/src/core/probe/bootstrap.ts

@@ -0,0 +1,34 @@
+/**
+ * Probe registry bootstrap (m-17 / ARV-49).
+ *
+ * Called once from the CLI program init. Imports each Probe class and
+ * runs `registerProbe`, which validates the contract from `types.ts`
+ * and throws if a slot is missing. Boot-time failure is louder than
+ * runtime — adding a new probe class without --dry-run / --report
+ * support won't ship; that's the whole point of the m-17 contract.
+ *
+ * Idempotent: repeated calls are no-ops (matters for unit tests that
+ * run the bootstrap multiple times).
+ */
+import { listProbes, registerProbe } from "./registry.ts";
+import { SecurityProbe } from "./security-probe-class.ts";
+import { MassAssignmentProbe } from "./mass-assignment-probe-class.ts";
+import { StaticProbe } from "./static-probe-class.ts";
+
+let bootstrapped = false;
+
+export function bootstrapProbes(): void {
+  if (bootstrapped) return;
+  if (listProbes().length === 0) {
+    registerProbe(new StaticProbe());
+    registerProbe(new MassAssignmentProbe());
+    registerProbe(new SecurityProbe());
+  }
+  bootstrapped = true;
+}
+
+/** Test helper — resets the singleton so the next `bootstrapProbes()`
+ *  re-registers from scratch. Pair with `clearProbes()` from registry. */
+export function resetBootstrap(): void {
+  bootstrapped = false;
+}