@vaudience/aigentflow-flow-validator 0.15.3

package/dist/index.d.cts

@@ -0,0 +1,291 @@
+/** Severity of a validation issue. `info` is reserved for future lints. */
+type Severity = 'error' | 'warning' | 'info';
+/**
+ * A single validation finding. The same shape is used for errors and
+ * warnings; warnings simply carry `severity: 'warning'` and never set
+ * {@link ValidationResult.valid} to false.
+ */
+interface ValidationIssue {
+    /** Dotted field path, e.g. `steps.fetch.query.url`. */
+    field: string;
+    /** Human-readable description of the problem. */
+    message: string;
+    /** Stable, machine-readable code (parity contract). */
+    code: string;
+    /** Severity. */
+    severity: Severity;
+    /** Step ID when the issue is step-specific. */
+    stepId?: string;
+    /** 1-based line in the source YAML, when known. */
+    line?: number;
+    /** 1-based column in the source YAML, when known. */
+    column?: number;
+    /** Extra context (e.g. the available step names). */
+    context?: string;
+    /** Suggested fix. */
+    suggestion?: string;
+}
+/** Roll-up statistics for a validation run. */
+interface ValidationSummary {
+    totalSteps: number;
+    validSteps: number;
+    errorCount: number;
+    warningCount: number;
+    templatesFound: number;
+    templatesValid: number;
+}
+/** The complete result of validating one flow. */
+interface ValidationResult {
+    /** True when there are zero `error`-severity issues. */
+    valid: boolean;
+    /** Error-severity issues. A non-empty list means `valid` is false. */
+    errors: ValidationIssue[];
+    /** Warning-severity issues. Never affect `valid`. */
+    warnings: ValidationIssue[];
+    /** Roll-up statistics. */
+    summary: ValidationSummary;
+}
+/** Options accepted by {@link validateFlow} and {@link validateFlowObject}. */
+interface ValidateOptions {
+    /**
+     * When true, an unrecognised orchestrator tool name and an unknown template
+     * function are reported as `error` instead of `warning`. Off by default
+     * because the vendored allow-lists can lag the live AIgentFlow registries,
+     * and a false-positive error is worse than a missed lint. See PARITY.md.
+     */
+    strictRegistries?: boolean;
+}
+interface PropertyDefinition {
+    type?: string;
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+    default?: unknown;
+    format?: string;
+    properties?: Record<string, PropertyDefinition>;
+    validation?: string;
+    items?: PropertyDefinition;
+    min_items?: number;
+    max_items?: number;
+}
+type QueryDefinition = PropertyDefinition;
+interface ErrorStrategyDefinition {
+    action?: string;
+    max_retries?: number;
+    retry_delay?: string;
+    goto_step?: string;
+    exponential_backoff?: boolean;
+    max_delay?: string;
+    backoff_multiplier?: number;
+    jitter?: boolean;
+    retry_on?: string[];
+}
+interface NextCondition {
+    if?: string;
+    /**
+     * The branch target. The YAML key is `goto`, NOT `goto_step` — this is the
+     * ONE place in the whole grammar spelled that way (`ConditionDefinition.GotoStep`
+     * carries `yaml:"goto"`, aigentflow.domain.step.go:134), while the flow-level
+     * and step-level `error_strategy` and `quality_gate` all use `goto_step`.
+     * Reading the wrong key here silently disabled every conditional-branch check.
+     */
+    goto?: string;
+    /** Present only so the misspelling can be REPORTED; AIgentFlow's strict parser rejects it. */
+    goto_step?: string;
+}
+interface ParallelDefinition {
+    rendezvous?: string;
+    steps?: string[];
+    resolution?: string;
+}
+interface NextLogicDefinition {
+    default?: string;
+    conditions?: NextCondition[];
+    parallel?: ParallelDefinition;
+}
+interface ThrottleDefinition {
+    delay?: string;
+    batch_size?: number;
+    batch_delay?: string;
+}
+interface ForEachDefinition {
+    items?: string;
+    as?: string;
+    max_parallel?: number;
+    resolution?: string;
+    throttle?: ThrottleDefinition;
+}
+interface LoopSubStep {
+    id?: string;
+    executor?: string;
+    credential?: string;
+    credentials?: Record<string, CredentialBinding | null>;
+    output_schema?: InputSchema;
+    [key: string]: unknown;
+}
+/**
+ * `quality_gate:` step block (DC-CP-8). An LLM-as-judge scores the step's own
+ * output against `rubric`; `passed = score >= threshold`. On failure the step
+ * is routed by `on_fail`.
+ */
+interface QualityGateDefinition {
+    rubric?: string;
+    threshold?: number;
+    model?: string;
+    provider?: string;
+    on_fail?: string;
+    goto_step?: string;
+    max_retries?: number;
+}
+interface LoopDefinition {
+    while?: string;
+    max_iterations?: number;
+    steps?: LoopSubStep[];
+}
+interface CredentialBinding {
+    source?: string;
+    inject_as?: string;
+}
+interface ResponseExpectationField {
+    type?: string;
+    required?: boolean | string;
+    items?: PropertyDefinition;
+}
+interface StepDefinition {
+    executor?: string;
+    query?: Record<string, unknown>;
+    pre_processing?: unknown[];
+    post_processing?: unknown[];
+    response_expectation?: Record<string, ResponseExpectationField>;
+    /** Evaluation mode (e.g. `raw-text`). `response_expectation` is read only when this is set. */
+    response_evaluation?: string;
+    next?: NextLogicDefinition;
+    error_strategy?: ErrorStrategyDefinition;
+    for_each?: ForEachDefinition;
+    loop?: LoopDefinition;
+    /**
+     * Bounds each executor invocation of the step (a Go duration, or
+     * "none"/"never"/"infinite"). Unparseable, or on a `loop:` step, it bounds
+     * nothing — see `step_max_duration_ignored`.
+     */
+    max_duration?: string;
+    credential?: string;
+    credentials?: Record<string, CredentialBinding | null>;
+    output_schema?: InputSchema;
+    quality_gate?: QualityGateDefinition;
+    [key: string]: unknown;
+}
+interface ExpressionFunctionDefinition {
+    package?: string;
+    function?: string;
+}
+interface VisibleWhenPredicate {
+    field?: string;
+    equals?: unknown;
+    in?: unknown[];
+}
+interface InputSchemaField {
+    name?: string;
+    type?: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: string[];
+    min?: number;
+    max?: number;
+    min_length?: number;
+    max_length?: number;
+    min_items?: number;
+    max_items?: number;
+    pattern?: string;
+    accept?: string[];
+    max_size?: number;
+    visible_when?: VisibleWhenPredicate;
+}
+interface InputSchema {
+    version?: number;
+    fields?: InputSchemaField[];
+}
+interface OrchestratorTrigger {
+    type?: string;
+    interval?: string;
+}
+interface OrchestratorDefinition {
+    exons?: string;
+    agentic?: boolean;
+    mode?: string;
+    triggers?: OrchestratorTrigger[];
+    tools?: string[];
+    max_turns?: number;
+    human_question_timeout?: string;
+    human_question_timeout_response?: string;
+}
+interface Flow {
+    aigentflow_version?: string;
+    name?: string;
+    version?: string;
+    description?: string;
+    handle?: string;
+    visibility?: string;
+    start?: string;
+    steps?: Record<string, StepDefinition>;
+    query?: Record<string, QueryDefinition>;
+    output?: string[];
+    error_strategy?: ErrorStrategyDefinition;
+    expression_functions?: ExpressionFunctionDefinition[];
+    constraints?: Record<string, unknown>;
+    currency?: string;
+    max_duration?: string;
+    orchestrator?: OrchestratorDefinition;
+    campaign?: Record<string, unknown>;
+    checkpoint?: Record<string, unknown>;
+    input_schema?: InputSchema;
+    classification?: Record<string, unknown>;
+    is_template?: boolean;
+    template?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+
+/** The AIgentFlow version whose flow schema this validator tracks. */
+declare const SPEC_VERSION: string;
+/** Current supported `input_schema.version`. */
+declare const INPUT_SCHEMA_VERSION: number;
+
+/** Result of parsing flow YAML. */
+interface ParseOutput {
+    /** The parsed flow object, present only when there are no parse errors. */
+    flow?: Flow;
+    /** Fatal YAML syntax / structure errors. Non-empty means `flow` is absent. */
+    parseErrors: ValidationIssue[];
+    /** Non-fatal YAML warnings (e.g. deprecated tags). */
+    parseWarnings: ValidationIssue[];
+    /**
+     * The SOURCE spelling of every number and boolean scalar, keyed by field path
+     * (`mock_scenarios.s.fetch.delay`). The reference decodes a scalar into a Go
+     * `string` field as its source text, so `delay: 0.0` arrives there as "0.0"
+     * (not a Go duration) while the parsed value here is the number 0. Present
+     * whenever `flow` is.
+     */
+    scalarSources?: ReadonlyMap<string, string>;
+}
+/**
+ * Parse flow YAML into a {@link Flow} object plus structured parse diagnostics.
+ * Never throws — malformed input is reported via `parseErrors`.
+ */
+declare function parseFlow(yamlText: string): ParseOutput;
+
+/**
+ * Validate an already-parsed flow object. Use this when you have a plain
+ * object (e.g. from your own YAML/JSON loader); use {@link validateFlow} to
+ * parse YAML text and validate in one step.
+ */
+declare function validateFlowObject(flow: unknown, opts?: ValidateOptions): ValidationResult;
+/**
+ * Parse flow YAML text and validate it. Parse errors (syntax, duplicate keys)
+ * are returned as `error`-severity issues; on a parse failure the structural
+ * validators are skipped because there is no usable document.
+ */
+declare function validateFlow(yamlText: string, opts?: ValidateOptions): ValidationResult;
+
+export { type Flow, INPUT_SCHEMA_VERSION, type ParseOutput, SPEC_VERSION, type Severity, type ValidateOptions, type ValidationIssue, type ValidationResult, type ValidationSummary, parseFlow, validateFlow, validateFlowObject };

package/dist/index.d.ts

@@ -0,0 +1,291 @@
+/** Severity of a validation issue. `info` is reserved for future lints. */
+type Severity = 'error' | 'warning' | 'info';
+/**
+ * A single validation finding. The same shape is used for errors and
+ * warnings; warnings simply carry `severity: 'warning'` and never set
+ * {@link ValidationResult.valid} to false.
+ */
+interface ValidationIssue {
+    /** Dotted field path, e.g. `steps.fetch.query.url`. */
+    field: string;
+    /** Human-readable description of the problem. */
+    message: string;
+    /** Stable, machine-readable code (parity contract). */
+    code: string;
+    /** Severity. */
+    severity: Severity;
+    /** Step ID when the issue is step-specific. */
+    stepId?: string;
+    /** 1-based line in the source YAML, when known. */
+    line?: number;
+    /** 1-based column in the source YAML, when known. */
+    column?: number;
+    /** Extra context (e.g. the available step names). */
+    context?: string;
+    /** Suggested fix. */
+    suggestion?: string;
+}
+/** Roll-up statistics for a validation run. */
+interface ValidationSummary {
+    totalSteps: number;
+    validSteps: number;
+    errorCount: number;
+    warningCount: number;
+    templatesFound: number;
+    templatesValid: number;
+}
+/** The complete result of validating one flow. */
+interface ValidationResult {
+    /** True when there are zero `error`-severity issues. */
+    valid: boolean;
+    /** Error-severity issues. A non-empty list means `valid` is false. */
+    errors: ValidationIssue[];
+    /** Warning-severity issues. Never affect `valid`. */
+    warnings: ValidationIssue[];
+    /** Roll-up statistics. */
+    summary: ValidationSummary;
+}
+/** Options accepted by {@link validateFlow} and {@link validateFlowObject}. */
+interface ValidateOptions {
+    /**
+     * When true, an unrecognised orchestrator tool name and an unknown template
+     * function are reported as `error` instead of `warning`. Off by default
+     * because the vendored allow-lists can lag the live AIgentFlow registries,
+     * and a false-positive error is worse than a missed lint. See PARITY.md.
+     */
+    strictRegistries?: boolean;
+}
+interface PropertyDefinition {
+    type?: string;
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+    default?: unknown;
+    format?: string;
+    properties?: Record<string, PropertyDefinition>;
+    validation?: string;
+    items?: PropertyDefinition;
+    min_items?: number;
+    max_items?: number;
+}
+type QueryDefinition = PropertyDefinition;
+interface ErrorStrategyDefinition {
+    action?: string;
+    max_retries?: number;
+    retry_delay?: string;
+    goto_step?: string;
+    exponential_backoff?: boolean;
+    max_delay?: string;
+    backoff_multiplier?: number;
+    jitter?: boolean;
+    retry_on?: string[];
+}
+interface NextCondition {
+    if?: string;
+    /**
+     * The branch target. The YAML key is `goto`, NOT `goto_step` — this is the
+     * ONE place in the whole grammar spelled that way (`ConditionDefinition.GotoStep`
+     * carries `yaml:"goto"`, aigentflow.domain.step.go:134), while the flow-level
+     * and step-level `error_strategy` and `quality_gate` all use `goto_step`.
+     * Reading the wrong key here silently disabled every conditional-branch check.
+     */
+    goto?: string;
+    /** Present only so the misspelling can be REPORTED; AIgentFlow's strict parser rejects it. */
+    goto_step?: string;
+}
+interface ParallelDefinition {
+    rendezvous?: string;
+    steps?: string[];
+    resolution?: string;
+}
+interface NextLogicDefinition {
+    default?: string;
+    conditions?: NextCondition[];
+    parallel?: ParallelDefinition;
+}
+interface ThrottleDefinition {
+    delay?: string;
+    batch_size?: number;
+    batch_delay?: string;
+}
+interface ForEachDefinition {
+    items?: string;
+    as?: string;
+    max_parallel?: number;
+    resolution?: string;
+    throttle?: ThrottleDefinition;
+}
+interface LoopSubStep {
+    id?: string;
+    executor?: string;
+    credential?: string;
+    credentials?: Record<string, CredentialBinding | null>;
+    output_schema?: InputSchema;
+    [key: string]: unknown;
+}
+/**
+ * `quality_gate:` step block (DC-CP-8). An LLM-as-judge scores the step's own
+ * output against `rubric`; `passed = score >= threshold`. On failure the step
+ * is routed by `on_fail`.
+ */
+interface QualityGateDefinition {
+    rubric?: string;
+    threshold?: number;
+    model?: string;
+    provider?: string;
+    on_fail?: string;
+    goto_step?: string;
+    max_retries?: number;
+}
+interface LoopDefinition {
+    while?: string;
+    max_iterations?: number;
+    steps?: LoopSubStep[];
+}
+interface CredentialBinding {
+    source?: string;
+    inject_as?: string;
+}
+interface ResponseExpectationField {
+    type?: string;
+    required?: boolean | string;
+    items?: PropertyDefinition;
+}
+interface StepDefinition {
+    executor?: string;
+    query?: Record<string, unknown>;
+    pre_processing?: unknown[];
+    post_processing?: unknown[];
+    response_expectation?: Record<string, ResponseExpectationField>;
+    /** Evaluation mode (e.g. `raw-text`). `response_expectation` is read only when this is set. */
+    response_evaluation?: string;
+    next?: NextLogicDefinition;
+    error_strategy?: ErrorStrategyDefinition;
+    for_each?: ForEachDefinition;
+    loop?: LoopDefinition;
+    /**
+     * Bounds each executor invocation of the step (a Go duration, or
+     * "none"/"never"/"infinite"). Unparseable, or on a `loop:` step, it bounds
+     * nothing — see `step_max_duration_ignored`.
+     */
+    max_duration?: string;
+    credential?: string;
+    credentials?: Record<string, CredentialBinding | null>;
+    output_schema?: InputSchema;
+    quality_gate?: QualityGateDefinition;
+    [key: string]: unknown;
+}
+interface ExpressionFunctionDefinition {
+    package?: string;
+    function?: string;
+}
+interface VisibleWhenPredicate {
+    field?: string;
+    equals?: unknown;
+    in?: unknown[];
+}
+interface InputSchemaField {
+    name?: string;
+    type?: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: string[];
+    min?: number;
+    max?: number;
+    min_length?: number;
+    max_length?: number;
+    min_items?: number;
+    max_items?: number;
+    pattern?: string;
+    accept?: string[];
+    max_size?: number;
+    visible_when?: VisibleWhenPredicate;
+}
+interface InputSchema {
+    version?: number;
+    fields?: InputSchemaField[];
+}
+interface OrchestratorTrigger {
+    type?: string;
+    interval?: string;
+}
+interface OrchestratorDefinition {
+    exons?: string;
+    agentic?: boolean;
+    mode?: string;
+    triggers?: OrchestratorTrigger[];
+    tools?: string[];
+    max_turns?: number;
+    human_question_timeout?: string;
+    human_question_timeout_response?: string;
+}
+interface Flow {
+    aigentflow_version?: string;
+    name?: string;
+    version?: string;
+    description?: string;
+    handle?: string;
+    visibility?: string;
+    start?: string;
+    steps?: Record<string, StepDefinition>;
+    query?: Record<string, QueryDefinition>;
+    output?: string[];
+    error_strategy?: ErrorStrategyDefinition;
+    expression_functions?: ExpressionFunctionDefinition[];
+    constraints?: Record<string, unknown>;
+    currency?: string;
+    max_duration?: string;
+    orchestrator?: OrchestratorDefinition;
+    campaign?: Record<string, unknown>;
+    checkpoint?: Record<string, unknown>;
+    input_schema?: InputSchema;
+    classification?: Record<string, unknown>;
+    is_template?: boolean;
+    template?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+
+/** The AIgentFlow version whose flow schema this validator tracks. */
+declare const SPEC_VERSION: string;
+/** Current supported `input_schema.version`. */
+declare const INPUT_SCHEMA_VERSION: number;
+
+/** Result of parsing flow YAML. */
+interface ParseOutput {
+    /** The parsed flow object, present only when there are no parse errors. */
+    flow?: Flow;
+    /** Fatal YAML syntax / structure errors. Non-empty means `flow` is absent. */
+    parseErrors: ValidationIssue[];
+    /** Non-fatal YAML warnings (e.g. deprecated tags). */
+    parseWarnings: ValidationIssue[];
+    /**
+     * The SOURCE spelling of every number and boolean scalar, keyed by field path
+     * (`mock_scenarios.s.fetch.delay`). The reference decodes a scalar into a Go
+     * `string` field as its source text, so `delay: 0.0` arrives there as "0.0"
+     * (not a Go duration) while the parsed value here is the number 0. Present
+     * whenever `flow` is.
+     */
+    scalarSources?: ReadonlyMap<string, string>;
+}
+/**
+ * Parse flow YAML into a {@link Flow} object plus structured parse diagnostics.
+ * Never throws — malformed input is reported via `parseErrors`.
+ */
+declare function parseFlow(yamlText: string): ParseOutput;
+
+/**
+ * Validate an already-parsed flow object. Use this when you have a plain
+ * object (e.g. from your own YAML/JSON loader); use {@link validateFlow} to
+ * parse YAML text and validate in one step.
+ */
+declare function validateFlowObject(flow: unknown, opts?: ValidateOptions): ValidationResult;
+/**
+ * Parse flow YAML text and validate it. Parse errors (syntax, duplicate keys)
+ * are returned as `error`-severity issues; on a parse failure the structural
+ * validators are skipped because there is no usable document.
+ */
+declare function validateFlow(yamlText: string, opts?: ValidateOptions): ValidationResult;
+
+export { type Flow, INPUT_SCHEMA_VERSION, type ParseOutput, SPEC_VERSION, type Severity, type ValidateOptions, type ValidationIssue, type ValidationResult, type ValidationSummary, parseFlow, validateFlow, validateFlowObject };