Surface Zigflow expression capabilities for tooling and MCP consumers #459

Originally from #420 (comment) by @yoricksmeets

Summary

Zigflow now performs expression parsing, compilation and determinism analysis during validation.

As part of this work, Zigflow has effectively defined its own expression environment:

• Supported jq builtins
• Supported Zigflow functions
• Supported Zigflow variables
• Deterministic functions
• Non-deterministic functions
• Validation rules around where expressions may be used

These capabilities are currently encoded in code (jqFuncs, deterministicBuiltins, compiler options, determinism analysis), but are not surfaced to users or tooling.

Problem

Tooling currently has no authoritative way to discover:

• Which functions are available
• Which variables are available
• Which functions are deterministic
• Which functions are only valid in specific contexts (for example Set)
• What the effective Zigflow subset of jq looks like

This makes it harder to build:

• Zigflow Studio
• MCP integrations
• AI-assisted workflow authoring
• Editor autocomplete
• Expression validation tooling
• Documentation generation

Consumers must currently reverse-engineer these capabilities from source code.

Proposal

Create a public representation of the Zigflow expression environment.

Potential outputs could include:

CLI

zigflow expressions list

Example:

Functions:
  uuid          (non-deterministic)
  timestamp     (non-deterministic)
  now           (non-deterministic)
  slugify       (deterministic)

Variables:
  $input
  $data
  $context
  $output
  $env

MCP

Expose expression capabilities through a dedicated MCP tool or metadata endpoint.

Example:

{
  "functions": [
    {
      "name": "uuid",
      "deterministic": false
    }
  ],
  "variables": [
    "$input",
    "$data",
    "$context",
    "$output",
    "$env"
  ]
}

Documentation

Generate expression reference documentation from the same source of truth.

Goals

• Single source of truth for supported expression capabilities
• No duplication between runtime, validation and documentation
• Enable richer tooling and autocomplete
• Enable AI-assisted authoring to discover available functions and variables
• Make the effective Zigflow expression language visible to users

Non-goals

• Changing validation behaviour
• Expanding expression capabilities
• Replacing jq
• Introducing a new expression language

Acceptance criteria

• Expression capabilities are discoverable programmatically
• Runtime and validation derive from the same capability definitions
• Tooling can determine whether a function is deterministic
• Tooling can determine which variables are available
• Documentation can be generated from the same source of truth