Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

9.9 KB
Raw Blame
import { AP_FUNCTIONS } from '@activepieces/core-formula'
import { isNil } from '@activepieces/core-utils'
import { BranchExecutionType, flowStructureUtil, FlowTrigger, FlowTriggerType, Step } from '@activepieces/shared'

function validateFlow({ trigger }: { trigger: FlowTrigger }): ValidationResult {
    const allSteps = flowStructureUtil.getAllSteps(trigger)
    const skippedStepNames = flowStructureUtil.getSkippedStepNames({ trigger })
    const allStepNames = new Set(allSteps.map(s => s.name))
    const issues: ValidationIssue[] = []

    if (trigger.type === FlowTriggerType.EMPTY) {
        issues.push({ category: 'step_validity', severity: 'error', stepName: 'trigger', message: 'Trigger is not configured (use ap_update_trigger).' })
    }

    const seenSteps = new Set<string>()
    let validCount = 0
    let invalidCount = 0
    let skippedCount = 0

    for (const step of allSteps) {
        if (skippedStepNames.has(step.name)) {
            skippedCount++
            seenSteps.add(step.name)
            continue
        }
        if (step.valid) {
            validCount++
        }
        else {
            invalidCount++
            if (!flowStructureUtil.isTrigger(step.type)) {
                issues.push({ category: 'step_validity', severity: 'error', stepName: step.name, message: `"${step.displayName}" is invalid (use ap_update_step to fix).` })
            }
        }

        const strings = collectStringValues({ step })
        const bareFunctions = [...new Set(strings.flatMap((value) => findBareFormulaFunctions({ value })))]
        for (const fn of bareFunctions) {
            issues.push({ category: 'template_reference', severity: 'error', stepName: step.name, message: `"${step.displayName}" uses the formula function ${fn}() inside {{ }}, which only holds step references. Write it as ap-formula-v1::{${fn}({{step_1['output'].field}})}::ap-formula-v1, with single braces around the formula.` })
        }
        const seenRefs = new Set<string>()
        for (const str of strings) {
            const refs = extractReferencedStepNames({ value: str })
            for (const ref of refs) {
                if (seenRefs.has(ref)) continue
                seenRefs.add(ref)
                if (!allStepNames.has(ref)) {
                    issues.push({ category: 'template_reference', severity: 'error', stepName: step.name, message: `"${step.displayName}" references "{{${ref}...}}" which does not exist in the flow.` })
                }
                else if (!seenSteps.has(ref)) {
                    issues.push({ category: 'template_reference', severity: 'error', stepName: step.name, message: `"${step.displayName}" references "{{${ref}...}}" which comes AFTER it in execution order.` })
                }
            }
        }

        if (flowStructureUtil.isBranchedAction(step)) {
            const { children, settings } = step
            const branches = settings.branches ?? []
            for (let i = 0; i < children.length; i++) {
                if (isNil(children[i])) {
                    const branchName = branches[i]?.branchName ?? `Branch ${i}`
                    const isFallback = branches[i]?.branchType === BranchExecutionType.FALLBACK
                    issues.push({
                        category: 'empty_branch',
                        severity: isFallback ? 'info' : 'warning',
                        stepName: step.name,
                        message: isFallback
                            ? `"${step.displayName}" has an empty fallback branch: "${branchName}". This is fine if the unmatched case intentionally does nothing.`
                            : `"${step.displayName}" has empty branch: "${branchName}".`,
                    })
                }
            }
        }

        seenSteps.add(step.name)
    }

    return { totalSteps: allSteps.length, validSteps: validCount, invalidSteps: invalidCount, skippedSteps: skippedCount, issues }
}

function collectStringValues({ step }: { step: Step }): string[] {
    const result: string[] = []

    if ('settings' in step && typeof step.settings === 'object' && step.settings !== null) {
        const settings = step.settings as Record<string, unknown>

        if ('input' in settings && typeof settings.input === 'object' && settings.input !== null) {
            walkValues(settings.input, (val) => {
                if (typeof val === 'string') result.push(val)
            })
        }

        if ('items' in settings && typeof settings.items === 'string') {
            result.push(settings.items)
        }

        if ('branches' in settings && Array.isArray(settings.branches)) {
            for (const branch of settings.branches) {
                if (typeof branch === 'object' && branch !== null && 'conditions' in branch && Array.isArray(branch.conditions)) {
                    for (const group of branch.conditions) {
                        if (!Array.isArray(group)) continue
                        for (const cond of group) {
                            if (typeof cond === 'object' && cond !== null) {
                                if ('firstValue' in cond && typeof cond.firstValue === 'string') result.push(cond.firstValue)
                                if ('secondValue' in cond && typeof cond.secondValue === 'string') result.push(cond.secondValue)
                            }
                        }
                    }
                }
            }
        }
    }

    return result
}

function walkValues(obj: unknown, fn: (val: unknown) => void): void {
    if (obj === null || obj === undefined) return
    fn(obj)
    if (Array.isArray(obj)) {
        for (const item of obj) walkValues(item, fn)
    }
    else if (typeof obj === 'object') {
        for (const val of Object.values(obj)) walkValues(val, fn)
    }
}

function extractReferencedStepNames({ value }: { value: string }): string[] {
    const regex = /\{\{\s*(\w+)\s*(\()?/g
    const names = new Set<string>()
    let match
    while ((match = regex.exec(value)) !== null) {
        const name = match[1]
        const isFunctionCall = match[2] !== undefined
        if (name !== 'connections' && !isFunctionCall) {
            names.add(name)
        }
    }
    return [...names]
}

function findBareFormulaFunctions({ value }: { value: string }): string[] {
    const outsideFormulas = value.replace(WRAPPED_FORMULA, '')
    const called = [...outsideFormulas.matchAll(BARE_FUNCTION_CALL)].map((match) => match[1])
    return [...new Set(called.filter((name) => FORMULA_FUNCTION_NAMES.has(comparableFunctionName(name))))]
}

function comparableFunctionName(name: string): string {
    return name.toLowerCase().replace(/_/g, '')
}

const WRAPPED_FORMULA = /ap-formula-v(\d+)::\{[\s\S]*?\}::ap-formula-v\1/g
const BARE_FUNCTION_CALL = /\{\{\s*([A-Za-z_]\w*)\s*\(/g
const FORMULA_FUNCTION_NAMES = new Set(AP_FUNCTIONS.map((fn) => comparableFunctionName(fn.name)))
const CATEGORY_ORDER: ValidationIssue['category'][] = ['step_validity', 'template_reference', 'empty_branch']
const CATEGORY_LABELS: Record<ValidationIssue['category'], string> = {
    step_validity: 'Step Validity',
    template_reference: 'Template References',
    empty_branch: 'Empty Branches',
}

function blockingIssues(issues: ValidationIssue[]): ValidationIssue[] {
    return issues.filter(i => i.severity !== 'info')
}

function hasNoBlockingIssues(issues: ValidationIssue[]): boolean {
    return blockingIssues(issues).length === 0
}

function formatInfoNotes(infoIssues: ValidationIssue[]): string[] {
    if (infoIssues.length === 0) {
        return []
    }
    return ['', 'Notes (non-blocking):', ...infoIssues.map(i => `- ${i.stepName}: ${i.message}`)]
}

function formatValidationResult({ result, flowDisplayName }: { result: ValidationResult, flowDisplayName: string }): string {
    const blockingIssues = result.issues.filter(i => i.severity !== 'info')
    const infoIssues = result.issues.filter(i => i.severity === 'info')

    if (blockingIssues.length === 0 && result.validSteps > 0) {
        const skippedNote = result.skippedSteps > 0 ? `, ${result.skippedSteps} skipped` : ''
        return [`✅ Flow "${flowDisplayName}" is ready to publish (${result.totalSteps} steps, ${result.validSteps} valid${skippedNote}).`, ...formatInfoNotes(infoIssues)].join('\n')
    }

    if (blockingIssues.length === 0 && result.validSteps === 0) {
        return [`⚠️ Flow "${flowDisplayName}" has no valid steps (${result.totalSteps} total). Configure the trigger and actions before publishing.`, ...formatInfoNotes(infoIssues)].join('\n')
    }

    const grouped = new Map<ValidationIssue['category'], ValidationIssue[]>()
    for (const issue of blockingIssues) {
        const list = grouped.get(issue.category) ?? []
        list.push(issue)
        grouped.set(issue.category, list)
    }

    const lines: string[] = []
    lines.push(`⚠️ Flow "${flowDisplayName}" has ${blockingIssues.length} issue(s):`)
    lines.push('')

    for (const category of CATEGORY_ORDER) {
        const issues = grouped.get(category)
        if (issues && issues.length > 0) {
            lines.push(`${CATEGORY_LABELS[category]}:`)
            for (const issue of issues) lines.push(`- ${issue.stepName}: ${issue.message}`)
            lines.push('')
        }
    }

    lines.push(`Summary: ${result.totalSteps} total, ${result.validSteps} valid, ${result.invalidSteps} invalid, ${result.skippedSteps} skipped`)

    return [...lines, ...formatInfoNotes(infoIssues)].join('\n')
}

type ValidationSeverity = 'error' | 'warning' | 'info'

type ValidationIssue = {
    category: 'step_validity' | 'template_reference' | 'empty_branch'
    severity: ValidationSeverity
    stepName: string
    message: string
}

type ValidationResult = {
    totalSteps: number
    validSteps: number
    invalidSteps: number
    skippedSteps: number
    issues: ValidationIssue[]
}

export const flowValidation = {
    validateFlow,
    blockingIssues,
    hasNoBlockingIssues,
    formatValidationResult,
}

export type { ValidationIssue, ValidationResult }