fg-tracker-mcp 0.7.0 → 0.8.0

package/dist/loadtest/scenario.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Roteiro (`document`) e plano (estilo k6) da Simulação de ambiente — CONTRATO.md §28.2 e §28.3.
+ * Esquemas zod com descrições em pt-BR para o agente, validação com caminhos precisos, avisos
+ * semânticos (variáveis não definidas, senhas literais, efeitos externos) e presets de plano.
+ */
+import { z } from 'zod';
+/** Converte "30s", "10m", "1h30m", "500ms" (ou número em segundos) para milissegundos; `null` se inválida. */
+export declare function parseDuration(value: string | number): number | null;
+/** Formata milissegundos no estilo k6: 90000 → "1m30s", 7200000 → "2h", 500 → "500ms". */
+export declare function formatDuration(ms: number): string;
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+export declare const extractSchema: z.ZodObject<{
+    var: z.ZodString;
+    from: z.ZodEnum<{
+        status: "status";
+        json: "json";
+        header: "header";
+        regex: "regex";
+    }>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+    in: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"json">;
+    path: z.ZodString;
+    exists: z.ZodOptional<z.ZodBoolean>;
+    equals: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"bodyContains">;
+    value: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"maxDurationMs">;
+    value: z.ZodNumber;
+}, z.core.$strict>], "type">;
+export declare const stepSchema: z.ZodObject<{
+    name: z.ZodString;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+        PUT: "PUT";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+    }>;
+    path: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodUnknown>;
+    extract: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        var: z.ZodString;
+        from: z.ZodEnum<{
+            status: "status";
+            json: "json";
+            header: "header";
+            regex: "regex";
+        }>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    checks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"status">;
+        in: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"json">;
+        path: z.ZodString;
+        exists: z.ZodOptional<z.ZodBoolean>;
+        equals: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bodyContains">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"maxDurationMs">;
+        value: z.ZodNumber;
+    }, z.core.$strict>], "type">>>;
+    thinkTimeMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    skipIf: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const scenarioSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        thinkTimeMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>>;
+    }, z.core.$strict>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    setup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            PUT: "PUT";
+            HEAD: "HEAD";
+            OPTIONS: "OPTIONS";
+        }>;
+        path: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        extract: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            var: z.ZodString;
+            from: z.ZodEnum<{
+                status: "status";
+                json: "json";
+                header: "header";
+                regex: "regex";
+            }>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        checks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"status">;
+            in: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"json">;
+            path: z.ZodString;
+            exists: z.ZodOptional<z.ZodBoolean>;
+            equals: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"bodyContains">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"maxDurationMs">;
+            value: z.ZodNumber;
+        }, z.core.$strict>], "type">>>;
+        thinkTimeMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        skipIf: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            PUT: "PUT";
+            HEAD: "HEAD";
+            OPTIONS: "OPTIONS";
+        }>;
+        path: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        extract: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            var: z.ZodString;
+            from: z.ZodEnum<{
+                status: "status";
+                json: "json";
+                header: "header";
+                regex: "regex";
+            }>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        checks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"status">;
+            in: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"json">;
+            path: z.ZodString;
+            exists: z.ZodOptional<z.ZodBoolean>;
+            equals: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"bodyContains">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"maxDurationMs">;
+            value: z.ZodNumber;
+        }, z.core.$strict>], "type">>>;
+        thinkTimeMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        skipIf: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    teardown: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            PUT: "PUT";
+            HEAD: "HEAD";
+            OPTIONS: "OPTIONS";
+        }>;
+        path: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        extract: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            var: z.ZodString;
+            from: z.ZodEnum<{
+                status: "status";
+                json: "json";
+                header: "header";
+                regex: "regex";
+            }>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        checks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"status">;
+            in: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"json">;
+            path: z.ZodString;
+            exists: z.ZodOptional<z.ZodBoolean>;
+            equals: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"bodyContains">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"maxDurationMs">;
+            value: z.ZodNumber;
+        }, z.core.$strict>], "type">>>;
+        thinkTimeMs: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        skipIf: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type LoadtestScenario = z.infer<typeof scenarioSchema>;
+export type LoadtestStep = z.infer<typeof stepSchema>;
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+/** Converte o caminho do zod em notação `steps[1].checks[0].in`. */
+export declare function formatIssuePath(path: ReadonlyArray<PropertyKey>): string;
+export declare function zodIssues(error: z.ZodError): ValidationIssue[];
+export declare const EXTERNAL_EFFECT_RE: RegExp;
+export interface ExternalEffectWarning {
+    step: string;
+    section: 'setup' | 'steps' | 'teardown';
+    method: string;
+    path: string;
+    reason: string;
+}
+export declare function externalEffect(method: string, path: string): string | null;
+export interface ScenarioSummary {
+    name: string;
+    baseUrl: string | null;
+    setup: string[];
+    steps: string[];
+    teardown: string[];
+    extractedVars: string[];
+    checks: number;
+    checkTypes: Record<string, number>;
+    usesCredentials: boolean;
+    externalEffects: ExternalEffectWarning[];
+    warnings: string[];
+}
+/** Resumo e avisos semânticos de um roteiro já validado. */
+export declare function summarizeScenario(scenario: LoadtestScenario): ScenarioSummary;
+export type ScenarioValidation = {
+    ok: true;
+    scenario: LoadtestScenario;
+    summary: ScenarioSummary;
+    issues: [];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+export declare function validateScenario(input: unknown): ScenarioValidation;
+export declare const EXECUTORS: readonly ["constant-vus", "ramping-vus", "constant-arrival-rate", "ramping-arrival-rate", "shared-iterations", "per-vu-iterations"];
+export declare const PRESETS: readonly ["smoke", "load", "stress", "spike", "soak", "breakpoint"];
+export type Preset = (typeof PRESETS)[number];
+export declare const planSchema: z.ZodObject<{
+    executor: z.ZodEnum<{
+        "constant-vus": "constant-vus";
+        "ramping-vus": "ramping-vus";
+        "constant-arrival-rate": "constant-arrival-rate";
+        "ramping-arrival-rate": "ramping-arrival-rate";
+        "shared-iterations": "shared-iterations";
+        "per-vu-iterations": "per-vu-iterations";
+    }>;
+    vus: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodString>;
+    stages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        duration: z.ZodString;
+        target: z.ZodNumber;
+    }, z.core.$strict>>>;
+    rate: z.ZodOptional<z.ZodNumber>;
+    timeUnit: z.ZodOptional<z.ZodString>;
+    preAllocatedVUs: z.ZodOptional<z.ZodNumber>;
+    maxVUs: z.ZodOptional<z.ZodNumber>;
+    iterations: z.ZodOptional<z.ZodNumber>;
+    gracefulStop: z.ZodOptional<z.ZodString>;
+    thresholds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    abortOnFail: z.ZodOptional<z.ZodBoolean>;
+    preset: z.ZodOptional<z.ZodEnum<{
+        custom: "custom";
+        smoke: "smoke";
+        load: "load";
+        stress: "stress";
+        spike: "spike";
+        soak: "soak";
+        breakpoint: "breakpoint";
+    }>>;
+}, z.core.$strict>;
+export type LoadtestPlan = z.infer<typeof planSchema>;
+export type PlanValidation = {
+    ok: true;
+    plan: LoadtestPlan;
+    issues: [];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+export declare function validatePlan(input: unknown): PlanValidation;
+export interface PlanShape {
+    executor: string;
+    /** Pico de VUs (arrival-rate: maxVUs ou preAllocatedVUs). */
+    peakVus: number;
+    /** Pico de iterações por segundo (só arrival-rate). */
+    peakIterationsPerSecond: number | null;
+    /** Duração total estimada em ms (sem gracefulStop; iterations: null). */
+    durationMs: number | null;
+    duration: string;
+}
+/** Pico de VUs/taxa e duração de um plano válido (para confirmação e avisos). */
+export declare function describePlan(plan: LoadtestPlan): PlanShape;
+export interface PresetOptions {
+    vus?: number;
+    /** Alvo de iterações por segundo; com ele os presets usam executores arrival-rate. */
+    targetRps?: number;
+    duration?: string;
+}
+/**
+ * Plano sugerido para cada preset (§28.3), no espírito dos tipos de teste do k6:
+ * smoke (1–5 VUs, 1 min), load (rampa + platô), stress (degraus acima do normal), spike (salto súbito),
+ * soak (carga média por horas) e breakpoint (rampa de arrival-rate até quebrar, abortOnFail).
+ */
+export declare function presetPlan(preset: Preset, options?: PresetOptions): LoadtestPlan;
+/** Avisos sobre um plano (tamanho, duração, ausência de thresholds). */
+export declare function planWarnings(plan: LoadtestPlan): string[];