@jevitate/cli 0.1.0 → 0.2.0

package/dist/check-suite.d.ts

@@ -0,0 +1,171 @@
+import { type EmulationSpec } from "@jevitate/playwright";
+import { type SuiteExploreOptions } from "./suite-explore-options.js";
+/**
+ * The `jevitate check --suite <file.json>` schema (#137). Validated in full BEFORE anything runs:
+ * a typo'd field, a wrong type or an unknown strategy is a refusal naming the path, never a
+ * silently skipped item. Relative file paths in the suite (invariants, storage state, journeys
+ * dir, verify-fix results, fixture/upload files, actor/persona states) resolve against the suite
+ * file's own directory.
+ *
+ * #195: goal and mission items take `jevitate explore`'s option set (`SUITE_EXPLORE_OPTIONS`, by
+ * the flag's camelCase name: `deny`, `apiPrefix`, `logSource`, `stallTimeout`, `persona`, …). A
+ * target sets them as defaults for every item they apply to; an item's own value replaces the
+ * target's. An item may also set its own `storageState` (`null`: start without the target's
+ * session, e.g. to drive a login), `secretFields`, and — goals — `fixtures`.
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "name": "shop-ci",
+ *   "budget": { "maxActions": 400, "maxMinutes": 20, "maxUsd": 2 },
+ *   "ai": "real",
+ *   "gateAdvisory": false,
+ *   "targets": [{
+ *     "name": "shop",
+ *     "url": "https://staging.shop.example/",
+ *     "allow": ["https://staging.shop.example"],
+ *     "storageState": "auth.json",
+ *     "secretFields": ["label=Password=env:SHOP_PASSWORD"],
+ *     "fixtures": "fixtures/shop.json",
+ *     "invariants": ["invariants/credits.json"],
+ *     "journeys": ["login", { "id": "checkout", "params": { "sku": "A1" }, "routes": ["/cart/**"] }],
+ *     "goals": [{ "name": "export", "goal": "export the report as CSV", "success": ["requestMade:GET /api/export"], "routes": ["/reports/**"] }],
+ *     "viewport": "1280x800",
+ *     "deny": ["/^Archive/i"], "apiPrefix": ["/api/"], "logSource": ["docker:shop-api"], "logDefect": ["error"],
+ *     "missions": [
+ *       { "strategy": "adversarial", "url": "https://staging.shop.example/settings", "maxActions": 60, "paid": ["/^Analyze/"] },
+ *       { "strategy": "exploratory", "device": "iPhone 13" }
+ *     ],
+ *     "verifyFix": [{ "result": "baseline/adversarial-….result.json", "fingerprint": "3fa2…" }]
+ *   }]
+ * }
+ * ```
+ */
+export type MissionStrategy = "coverage" | "exploratory" | "adversarial" | "feature" | "usability";
+export interface SuiteBudget {
+    /** Total executed browser actions across every item. */
+    readonly maxActions?: number;
+    /** Total wall-clock minutes. */
+    readonly maxMinutes?: number;
+    /** Total model spend (USD), as reported by the provider. */
+    readonly maxUsd?: number;
+}
+export interface SuiteJourney {
+    readonly id: string;
+    /** `viewport` ("375x812") or `device` ("iPhone 13"); default: the target's. */
+    readonly emulation?: EmulationSpec;
+    readonly params: Readonly<Record<string, string>>;
+    /** Route globs this Journey covers (for `--changed-routes`); default: its Recording's page routes. */
+    readonly routes?: readonly string[];
+    /** The item's own session (`null`: none, whatever the target's); default: the target's. */
+    readonly storageState?: string | null;
+    /** #247: a named environment (`.jevitate/environments.json`) to run the Journey against; default: its recorded site. */
+    readonly env?: string;
+    /** #247: an origin to run the Journey against (with `env`, replaces its baseUrl). */
+    readonly baseUrl?: string;
+}
+/** What goal and mission items may set beyond their own fields (#195). */
+export interface SuiteItemOverrides {
+    /** The item's own session (`null`: start fresh, without the target's); default: the target's. */
+    readonly storageState?: string | null;
+    /** The item's own `secretFields` (replacing the target's). */
+    readonly secretFields?: readonly string[];
+    /** `explore`'s generic options, overriding the target's defaults. */
+    readonly explore?: SuiteExploreOptions;
+}
+export interface SuiteGoal extends SuiteItemOverrides {
+    readonly name: string;
+    /** The item's own mission fixtures file (replacing the target's). */
+    readonly fixtures?: string;
+    /** `viewport` or `device`; default: the target's. */
+    readonly emulation?: EmulationSpec;
+    readonly goal: string;
+    readonly success: readonly string[];
+    readonly url?: string;
+    readonly successWhen?: "final" | "held";
+    readonly routes?: readonly string[];
+    readonly maxActions?: number;
+    readonly maxDecisions?: number;
+}
+export interface SuiteMission extends SuiteItemOverrides {
+    readonly name: string;
+    /** `viewport` or `device`; default: the target's. */
+    readonly emulation?: EmulationSpec;
+    readonly strategy: MissionStrategy;
+    readonly url?: string;
+    readonly routes?: readonly string[];
+    /** `feature`: the capability name. */
+    readonly feature?: string;
+    /** `usability`: the job and app class. */
+    readonly goal?: string;
+    readonly appClass?: string;
+    /** #225 — `usability`: independent completion checks on the job (goal-item semantics); none by default. */
+    readonly success?: readonly string[];
+    readonly successWhen?: "final" | "held";
+    readonly maxActions?: number;
+    readonly maxDecisions?: number;
+}
+export interface SuiteVerifyFix {
+    readonly name: string;
+    readonly result: string;
+    readonly fingerprint: string;
+    readonly replays?: number;
+    /** The item's own session (`null`: none, whatever the target's); default: the target's. */
+    readonly storageState?: string | null;
+}
+export interface SuiteTarget {
+    readonly name: string;
+    readonly url: string;
+    /** The default `viewport` ("1280x800") or `device` ("iPhone 13") for every item of the target. */
+    readonly emulation?: EmulationSpec;
+    readonly allow: readonly string[];
+    /** Applied to every item of the target — Journeys, goals, missions, verify-fix (#170). */
+    readonly storageState?: string;
+    /**
+     * `--secret-field` specs (`label=Password=env:APP_PASSWORD`, #170): the value is read from the
+     * environment when the check starts, never written in the suite. Typed by goal and usability
+     * items; also what the target's fixtures may authenticate with.
+     */
+    readonly secretFields?: readonly string[];
+    /** Mission fixtures file (#140/#144) run around each goal and Journey item; default: the targets.json one. */
+    readonly fixtures?: string;
+    readonly invariants: readonly string[];
+    readonly journeysDir?: string;
+    readonly journeys: readonly SuiteJourney[];
+    readonly goals: readonly SuiteGoal[];
+    readonly missions: readonly SuiteMission[];
+    readonly verifyFix: readonly SuiteVerifyFix[];
+    /** `explore`'s generic options: defaults for every goal and mission item they apply to (#195). */
+    readonly explore?: SuiteExploreOptions;
+}
+export interface CheckSuite {
+    readonly version: 1;
+    readonly name: string;
+    readonly budget: SuiteBudget;
+    readonly ai?: "real" | "fake";
+    /** Advisory findings (UX, 4xx-correlated console errors, Jev flags) fail the gate only when true. */
+    readonly gateAdvisory: boolean;
+    readonly targets: readonly SuiteTarget[];
+    /** The suite file (absolute). */
+    readonly path: string;
+}
+export declare class SuiteError extends Error {
+    readonly code: "E_CHECK_SUITE";
+    /** #213: each path-precise problem on its own (`$.targets[0].name: …`); the message joins them. */
+    readonly problems: readonly string[];
+    constructor(message: string, problems?: readonly string[]);
+}
+/**
+ * Each suite level's own field names; targets, goals and missions also take every generic explore
+ * option (`SUITE_EXPLORE_OPTIONS`).
+ */
+export declare const SUITE_FIELDS: {
+    readonly target: readonly ["name", "url", "allow", "storageState", "secretFields", "fixtures", "invariants", "journeysDir", "journeys", "goals", "missions", "verifyFix", "viewport", "device"];
+    readonly journey: readonly ["id", "params", "routes", "viewport", "device", "storageState", "env", "baseUrl"];
+    readonly goal: readonly ["name", "goal", "success", "url", "successWhen", "routes", "maxActions", "maxDecisions", "viewport", "device", "storageState", "secretFields", "fixtures"];
+    readonly mission: readonly ["name", "strategy", "url", "routes", "feature", "goal", "appClass", "success", "successWhen", "maxActions", "maxDecisions", "viewport", "device", "storageState", "secretFields"];
+    readonly verifyFix: readonly ["name", "result", "fingerprint", "replays", "storageState"];
+};
+/** Validates a parsed suite. `file` names it in every refusal; relative paths resolve against it. */
+export declare function parseSuite(raw: unknown, file: string): CheckSuite;
+export declare function loadSuite(file: string): CheckSuite;