:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { load } from 'js-yaml'
import { readFileSync } from 'node:fs'
import {
type Context,
type FunctionMap,
type JsonValue,
evaluateCondition,
evaluateTemplate,
evaluateValue,
planFunctions,
} from './expressions.ts'
export type Outcome = 'success' | 'failure' | 'cancelled' | 'skipped'
export const WORKFLOW_SITE = '<workflow>'
export interface StepStub {
outputs?: Record<string, string>
outcome?: Outcome
}
export interface Scenario {
name: string
github: Context
vars?: Record<string, string>
/** Stubbed step results by job id, then step id (or name). Steps the plan skips lose their stubbed outputs. */
steps?: Record<string, Record<string, StepStub>>
/** Overrides a job's evaluated outputs, for reusable-workflow calls and script-driven outputs. */
jobOutputs?: Record<string, Record<string, string>>
/** The run was cancelled before any job started, except those in `completedBeforeCancel`. */
cancelled?: boolean
completedBeforeCancel?: readonly string[]
}
export interface RawStep {
id?: string
name?: string
if?: unknown
uses?: string
run?: string
env?: Record<string, unknown>
with?: Record<string, unknown>
'continue-on-error'?: unknown
parallel?: RawStep[]
}
export interface RawJob {
name?: string
if?: unknown
needs?: string | string[]
uses?: string
env?: Record<string, unknown>
outputs?: Record<string, unknown>
steps?: RawStep[]
strategy?: { matrix?: unknown }
'continue-on-error'?: unknown
}
export interface Workflow {
name?: string
on?: unknown
env?: Record<string, unknown>
jobs: Record<string, RawJob>
}
export interface StepPlan {
index: number
id: string | undefined
name: string | undefined
uses: string | undefined
runs: boolean
}
export interface JobPlan {
id: string
outcome: Outcome
result: Outcome
outputs: Record<string, string>
steps: StepPlan[]
/** Number of matrix cells the job expands to; undefined when there is no matrix or it could not be evaluated. */
matrixCells: number | undefined
}
export interface PlanError {
job: string
step?: string
where: 'if' | 'env' | 'outputs' | 'matrix' | 'continue-on-error'
message: string
}
export interface WorkflowPlan {
jobs: Record<string, JobPlan>
errors: PlanError[]
}
interface StepContext {
outputs: Record<string, string>
outcome: Outcome
conclusion: Outcome
}
export function parseWorkflow(source: string): Workflow {
const parsed = load(source)
if (typeof parsed !== 'object' || parsed === null || typeof (parsed as Workflow).jobs !== 'object') {
throw new Error('workflow has no jobs')
}
return parsed as Workflow
}
export function loadWorkflow(path: string): Workflow {
return parseWorkflow(readFileSync(path, 'utf8'))
}
export function flattenSteps(steps: RawStep[] | undefined): RawStep[] {
return (steps ?? []).flatMap((step) => (Array.isArray(step.parallel) ? flattenSteps(step.parallel) : [step]))
}
function needIds(job: RawJob): string[] {
if (job.needs === undefined) {
return []
}
return Array.isArray(job.needs) ? job.needs : [job.needs]
}
function jobOrder(jobs: Record<string, RawJob>): string[] {
const order: string[] = []
const seen = new Set<string>()
const visit = (id: string): void => {
if (seen.has(id) || !(id in jobs)) {
return
}
seen.add(id)
for (const need of needIds(jobs[id]!)) {
visit(need)
}
order.push(id)
}
Object.keys(jobs).forEach(visit)
return order
}
function evaluateEnv(
raw: Record<string, unknown> | undefined,
context: Context,
functions: FunctionMap
): Record<string, string> {
const env: Record<string, string> = {}
for (const [key, value] of Object.entries(raw ?? {})) {
env[key] = evaluateTemplate(value, context, functions)
}
return env
}
export function countMatrixCells(rawMatrix: unknown, context: Context, functions: FunctionMap): number | undefined {
if (rawMatrix === undefined || rawMatrix === null) {
return undefined
}
const matrix = evaluateValue(rawMatrix, context, functions)
if (Array.isArray(matrix)) {
return matrix.length
}
if (typeof matrix !== 'object' || matrix === null) {
return undefined
}
const entries = matrix as Record<string, unknown>
const include = evaluateValue(entries['include'], context, functions)
if (include === null) {
return undefined
}
const includeCount = Array.isArray(include) ? include.length : 0
const axes = Object.entries(entries)
.filter(([key]) => key !== 'include' && key !== 'exclude')
.map(([, value]) => evaluateValue(value, context, functions))
if (axes.some((value) => value === null)) {
return undefined
}
const axisSizes = axes.map((value) => (Array.isArray(value) ? value.length : 1))
if (axisSizes.length === 0) {
return includeCount
}
return axisSizes.reduce((product, size) => product * size, 1) + includeCount
}
function toStepPlan(step: RawStep, index: number, runs: boolean): StepPlan {
return { index, id: step.id, name: step.name, uses: step.uses, runs }
}
function planSteps(
jobId: string,
steps: RawStep[],
context: Context,
env: Record<string, string>,
stubs: Record<string, StepStub>,
cancelled: boolean,
errors: PlanError[]
): { steps: StepPlan[]; stepContexts: Record<string, StepContext>; failed: boolean } {
const stepContexts: Record<string, StepContext> = {}
const plans: StepPlan[] = []
let failed = false
steps.forEach((step, index) => {
const stepStatus = planFunctions({
dependenciesSucceeded: !failed,
dependenciesFailed: failed,
cancelled,
})
const stepContext: Context = { ...context, steps: stepContexts as unknown as JsonValue }
let contextWithStepEnv: Context = { ...stepContext, env }
let runs = false
try {
contextWithStepEnv = { ...stepContext, env: { ...env, ...evaluateEnv(step.env, stepContext, stepStatus) } }
runs = evaluateCondition(step.if, contextWithStepEnv, stepStatus)
} catch (error) {
errors.push({ job: jobId, step: step.id ?? `#${index}`, where: 'if', message: String(error) })
}
const stub = stubs[step.id ?? ''] ?? stubs[step.name ?? '']
const outcome: Outcome = runs ? (stub?.outcome ?? 'success') : 'skipped'
let continueOnError = false
try {
continueOnError = evaluateTemplate(step['continue-on-error'], contextWithStepEnv, stepStatus) === 'true'
} catch (error) {
errors.push({
job: jobId,
step: step.id ?? `#${index}`,
where: 'continue-on-error',
message: String(error),
})
}
const conclusion: Outcome = outcome === 'failure' && continueOnError ? 'success' : outcome
if (outcome === 'failure' && !continueOnError) {
failed = true
}
if (step.id) {
stepContexts[step.id] = { outputs: runs ? (stub?.outputs ?? {}) : {}, outcome, conclusion }
}
plans.push(toStepPlan(step, index, runs))
})
return { steps: plans, stepContexts, failed }
}
export function planWorkflow(workflow: Workflow, scenario: Scenario): WorkflowPlan {
const errors: PlanError[] = []
const jobs: Record<string, JobPlan> = {}
const completed = new Set(scenario.completedBeforeCancel ?? [])
const baseContext: Context = {
github: scenario.github,
vars: scenario.vars ?? {},
inputs: {},
secrets: { GITHUB_TOKEN: 'stub-token' },
matrix: {},
runner: { os: 'Linux', arch: 'X64', name: 'workflow-plan' },
strategy: {},
}
let workflowEnv: Record<string, string> = {}
try {
workflowEnv = evaluateEnv(
workflow.env,
baseContext,
planFunctions({ dependenciesSucceeded: true, dependenciesFailed: false, cancelled: false })
)
} catch (error) {
errors.push({ job: WORKFLOW_SITE, where: 'env', message: String(error) })
}
for (const jobId of jobOrder(workflow.jobs)) {
const job = workflow.jobs[jobId]!
const cancelled = !!scenario.cancelled && !completed.has(jobId)
const needs = needIds(job)
const needsContext = Object.fromEntries(
needs.map((need) => [need, { result: jobs[need]?.result ?? 'success', outputs: jobs[need]?.outputs ?? {} }])
)
const needResults = Object.values(needsContext).map((need) => need.result)
const status = planFunctions({
dependenciesSucceeded: needResults.every((result) => result === 'success'),
dependenciesFailed: needResults.some((result) => result === 'failure'),
cancelled,
})
const contextWithoutEnv: Context = {
...baseContext,
needs: needsContext,
job: { status: 'success' },
}
let env: Record<string, string> = { ...workflowEnv }
try {
env = { ...env, ...evaluateEnv(job.env, contextWithoutEnv, status) }
} catch (error) {
errors.push({ job: jobId, where: 'env', message: String(error) })
}
const context: Context = { ...contextWithoutEnv, env }
let runs = false
try {
runs = evaluateCondition(job.if, context, status)
} catch (error) {
errors.push({ job: jobId, where: 'if', message: String(error) })
}
const allSteps = flattenSteps(job.steps)
if (!runs) {
const outcome: Outcome = cancelled ? 'cancelled' : 'skipped'
jobs[jobId] = {
id: jobId,
outcome,
result: outcome,
outputs: {},
steps: allSteps.map((step, index) => toStepPlan(step, index, false)),
matrixCells: undefined,
}
continue
}
let matrixCells: number | undefined
try {
matrixCells = countMatrixCells(job.strategy?.matrix, context, status)
} catch (error) {
errors.push({ job: jobId, where: 'matrix', message: String(error) })
}
const stepPlan = planSteps(jobId, allSteps, context, env, scenario.steps?.[jobId] ?? {}, cancelled, errors)
let outputs: Record<string, string> = {}
try {
outputs = evaluateEnv(
job.outputs,
{ ...context, steps: stepPlan.stepContexts as unknown as JsonValue },
status
)
} catch (error) {
errors.push({ job: jobId, where: 'outputs', message: String(error) })
}
for (const [key, value] of Object.entries(outputs)) {
outputs[key] = value.trim()
}
const outcome: Outcome = stepPlan.failed ? 'failure' : 'success'
let continueOnError = false
try {
continueOnError = evaluateTemplate(job['continue-on-error'], context, status) === 'true'
} catch (error) {
errors.push({ job: jobId, where: 'continue-on-error', message: String(error) })
}
jobs[jobId] = {
id: jobId,
outcome,
result: outcome === 'failure' && continueOnError ? 'success' : outcome,
outputs: { ...outputs, ...scenario.jobOutputs?.[jobId] },
steps: stepPlan.steps,
matrixCells,
}
}
return { jobs, errors }
}
export function formatPlanError(scenarioName: string, error: PlanError): string {
const site = error.step ? `${error.job}/${error.step}` : error.job
return `${scenarioName}: ${site} ${error.where}: ${error.message}`
}
export function runningJobs(plan: WorkflowPlan): string[] {
return Object.values(plan.jobs)
.filter((job) => job.result === 'success' || job.result === 'failure')
.map((job) => job.id)
}