version: "3"

# ============================================================================

# ============================================================================

includes:

rust:

taskfile: ./.task/languages/rust.yml

python:

taskfile: ./.task/languages/python.yml

node:

taskfile: ./.task/languages/node.yml

ruby:

taskfile: ./.task/languages/ruby.yml

php:

taskfile: ./.task/languages/php.yml

go:

taskfile: ./.task/languages/go.yml

java:

taskfile: ./.task/languages/java.yml

csharp:

taskfile: ./.task/languages/csharp.yml

elixir:

taskfile: ./.task/languages/elixir.yml

dart:

taskfile: ./.task/languages/dart.yml

swift:

taskfile: ./.task/languages/swift.yml

kotlin-android:

taskfile: ./.task/languages/kotlin_android.yml

zig:

taskfile: ./.task/languages/zig.yml

version:

taskfile: ./.task/tools/version-sync.yml

integrations:

taskfile: ./.task/tools/integrations.yml

plugin:

taskfile: ./.task/tools/plugin.yml

benchmark:

taskfile: ./.task/workflows/benchmark.yml

docs:

taskfile: ./.task/tools/docs.yml

demo:

taskfile: ./.task/tools/demo.yml

fixtures:

taskfile: ./.task/tools/fixtures.yml

test-apps:

taskfile: ./.task/tools/test-apps.yml

pdfium:

taskfile: ./.task/tools/pdfium.yml

_tools:

taskfile: ./.task/tools/general.yml

flatten: true

vars:

# MUST match the pin in .github/workflows/ci-lint.yaml's "Verify generated plugin bundles are

# current" step, whose own comment requires the two move in lockstep. They had drifted since

# v1.1.0 (here 4.11.3, CI 4.11.0) and 4.11.3's output does NOT satisfy 4.11.0's verify -- so

# running `task plugin:generate` and committing the result turned CI red. Bump both together.

AI_RULEZ_VERSION: "4.11.0"

tasks:

default:

desc: "List available tasks"

cmds:

- task --list

setup:

desc: "Install all dependencies and setup development environment"

cmds:

- task: rust:install

- alef setup

- task: governance:generate

- task: integrations:sync

- command -v poly >/dev/null 2>&1 || brew install goldziher/tap/poly

- poly hooks install

build:

desc: "Build Rust core library only (debug)"

cmds:

- task: build:core

build:release:

desc: "Build Rust core library only (release)"

cmds:

- task: rust:build:release

build:ci:

desc: "Build Rust core library in CI mode"

cmds:

- task: rust:build:ci

build:core:

desc: "Build Rust core library only (debug)"

cmds:

- task: rust:build:dev

build:bindings:

desc: "Build all language bindings"

cmds:

- task: alef:build

build:all:

desc: "Build Rust core library and all language bindings (debug)"

cmds:

- task: build:core

- task: build:bindings

build:cli:

desc: "Build the xberg CLI binary"

cmds:

- task: rust:cli:build

test:

desc: "Run Rust core tests"

cmds:

- task: rust:test

test:all:

desc: "Run all test suites (Rust core + bindings)"

cmds:

- task: test

- task: test:scripts

- alef test

test:scripts:

desc: "Run the contract tests for the repo's own shell and PowerShell scripts"

cmds:

- task: test:scripts:bats

- task: test:scripts:pester

test:scripts:pester:

desc: "Run the Pester contract tests for scripts/**/*.ps1"

vars:

# The same pin ci-scripts.yaml passes to install-pester, so a local run and a CI run

# exercise the same Pester.

PESTER_VERSION: "6.2.0"

preconditions:

- sh: command -v pwsh

msg: "pwsh is required for the Pester suites. Install PowerShell 7 or newer."

- sh: >-

pwsh -NoProfile -Command

'exit [int](@(Get-Module -ListAvailable Pester).Version -notcontains [version]"{{.PESTER_VERSION}}")'

msg: >-

Pester {{.PESTER_VERSION}} is missing. Install it with:

Install-Module Pester -RequiredVersion {{.PESTER_VERSION}} -Scope CurrentUser

cmds:

# Suites are DISCOVERED under scripts/tests/pester, not listed, so a new one is picked up

# with no registration -- the same property `bats --recursive` gives the shell side.

# Scoped to that directory rather than the whole tree so the walk never reaches .venv or

# node_modules, and found with `find` rather than `git ls-files` so a suite works before it

# is staged.

#

# The count is asserted non-empty: Invoke-Pester with no paths exits 0, so a stale scope

# would report a pass having run nothing.

#

# -PassThru with an explicit exit: a plain Invoke-Pester prints its failures and still

# returns 0, which would leave this task green with a red suite. ~keep

- |

pwsh -NoProfile -Command '

$suites = @(Get-ChildItem -Path scripts/tests/pester -Recurse -File -Filter "*.Tests.ps1")

if ($suites.Count -eq 0) { throw "no *.Tests.ps1 suites found under scripts/tests/pester" }

exit (Invoke-Pester -Path $suites.FullName -Output Detailed -PassThru).FailedCount'

test:scripts:bats:

desc: "Run the Bats contract tests for scripts/**/*.sh"

env:

# Suites load the shared helpers with `bats_load_library xberg-bats`, which searches

# BATS_LIB_PATH and nothing else. CI passes the same directory to run-bats via lib-path.

BATS_LIB_PATH: "{{.ROOT_DIR}}/scripts/tests/lib"

preconditions:

- sh: command -v bats

msg: "bats is required: brew install bats-core"

- sh: test -f scripts/tests/lib/xberg-bats/load.bash

msg: "shared Bats helpers are missing; run `task test:scripts:lib:sync`"

cmds:

- bats --recursive --print-output-on-failure scripts/tests/bats

test:scripts:lib:sync:

desc: "Refresh the vendored Bats helper library from xberg-io/actions"

cmds:

- scripts/task/sync-bats-lib.sh sync

test:scripts:lib:check:

desc: "Fail when the vendored Bats helper library has drifted from its pinned source"

cmds:

- scripts/task/sync-bats-lib.sh --check

lint:shell:

desc: "Format-check shell sources (poly does not format shell; see the comment below)"

cmds:

# poly runs shellcheck on shell but does NOT run shfmt: a tracked .sh mangled on purpose

# still passes `poly fmt --check` while `shfmt -l` flags it, in this repo and in

# xberg-io/actions, which has had [tools.shfmt] enabled all along. So formatting needs an

# explicit invocation. Indentation comes from .editorconfig, which shfmt reads natively.

#

# Scoped to scripts/tests for now. The other 119 tracked .sh files are 27 files away from

# clean, and reformatting release-path scripts that still have no coverage is the exact

# ordering this project exists to avoid. Widen the scope as suites land. ~keep

#

# scripts/tests/lib is excluded: it holds the VENDORED helper library, which has to stay

# byte-identical to its source in xberg-io/actions or `task test:scripts:lib:check` fails.

# .editorconfig would otherwise reformat it to two-space.

#

# The file list is built with find and then asserted non-empty. `git ls-files` misses files

# that are not staged yet, and shfmt with zero arguments reads stdin and exits 0 -- a lint

# task that silently checks nothing is worse than one that is absent. ~keep

- |

files=$(find scripts/tests -type f \( -name '*.bats' -o -name '*.sh' \) -not -path 'scripts/tests/lib/*')

if [ -z "$files" ]; then

echo "lint:shell matched no files under scripts/tests; the scope is stale" >&2

exit 1

fi

# shellcheck disable=SC2086

shfmt -d $files

test:bindings:

desc: "Run binding test suites only (skip Rust core)"

cmds:

- alef test

test:cov:

desc: "Run all tests with coverage"

cmds:

- task: rust:test:ci

- alef test --coverage

test:ci:

desc: "Run all tests with coverage (CI mode, alias for test:cov)"

cmds:

- task: test:cov

lint:

desc: "Lint all code via poly"

cmds:

- poly lint .

lint:check:

# `poly lint` never writes -- there is no autofix mode to opt out of, so

# this is a plain alias of `lint`, not a stricter check-only variant. ~keep

desc: "Lint all code via poly (alias of lint; poly lint never auto-fixes)"

cmds:

- poly lint .

format:

desc: "Format all code via poly"

cmds:

- poly fmt --fix .

format:check:

desc: "Check code formatting without modifications"

cmds:

- poly fmt --check .

check:

desc: "Run all checks (format + lint, no modifications)"

cmds:

- task: format:check

- task: lint:check

governance:generate:

desc: "Generate local AI governance files with the pinned ai-rulez version"

cmds:

- npx -y ai-rulez@{{.AI_RULEZ_VERSION}} generate

governance:validate:

desc: "Validate the root AI governance configuration"

cmds:

- npx -y ai-rulez@{{.AI_RULEZ_VERSION}} validate

governance:verify:

desc: "Validate that AI governance inputs resolve and render without modifying the checkout"

deps:

- governance:validate

cmds:

- |

set -euo pipefail

governance_verify_root="$(mktemp -d)"

trap 'rm -rf -- "$governance_verify_root"' EXIT

cp -R .ai-rulez "$governance_verify_root/.ai-rulez"

(

cd "$governance_verify_root"

npx -y ai-rulez@{{.AI_RULEZ_VERSION}} generate --no-configure-cli-mcp --quiet

)

check:android:

desc: "cargo check xberg-dart + xberg-ffi for Android ABIs"

cmds:

- task: rust:check:android

check:ios:

desc: "cargo check xberg-dart + xberg-swift for iOS targets (macOS only)"

cmds:

- task: rust:check:ios

check:mobile:

desc: "cargo check Android + iOS mobile targets"

cmds:

- task: rust:check:mobile

update:

desc: "Update all dependencies within major versions (minor patches only)"

cmds:

- task: rust:update

- task: python:update

- task: node:update

- task: ruby:update

- task: php:update

- task: go:update

- task: java:update

- task: csharp:update

- task: elixir:update

- task: dart:update

- task: swift:update

- task: kotlin-android:update

- task: zig:update

- task: integrations:update

- alef update

upgrade:

desc: "Upgrade all dependencies to latest including breaking changes"

cmds:

- rustup update stable

- task: rust:upgrade

- task: python:upgrade

- task: node:upgrade

- task: ruby:upgrade

- task: php:upgrade

- task: go:upgrade

- task: java:upgrade

- task: csharp:upgrade

- task: elixir:upgrade

- task: dart:upgrade

- task: swift:upgrade

- task: kotlin-android:upgrade

- task: zig:upgrade

- task: integrations:upgrade

- cmd: alef update --latest

ignore_error: true

- gau --update .

cov:rust:

desc: "Generate Rust coverage report"

cmds:

- task: rust:test:ci

cov:all:

desc: "Generate coverage for all languages"

cmds:

- task: rust:test:ci

- alef test --coverage

versions:sync:

desc: "Synchronize version from Cargo.toml to all package manifests"

cmds:

- task: version:sync

alef:generate:

desc: "Regenerate all Alef-managed outputs (formatting via poly, no build or snippet validation)"

cmds:

- alef all --clean --skip-snippet-validation

alef:verify:

desc: "Check Alef-generated files are up to date"

cmds:

- alef verify --exit-code

alef:build:

desc: "Build all language bindings"

cmds:

- alef build

alef:sync:

desc: "Sync version from Cargo.toml to all manifests"

cmds:

- alef sync-versions

alef:docs:

desc: "Generate API reference documentation"

cmds:

- alef docs

alef:verify:readme-paths:

desc: "Check every alef.toml readme/docs path (templates, snippets) resolves on disk"

cmds:

- python3 scripts/ci/check-alef-readme-paths.py alef.toml

alef:verify:ffi-formats:

desc: "Check the native FFI build still selects every document format (GH#1387)"

cmds:

- python3 scripts/ci/check-ffi-format-features.py alef.toml

alef:verify:fields:

desc: "Check every tracked config field is named in every generated binding surface (GH#1745)"

cmds:

- python3 scripts/ci/check-binding-field-coverage.py

supported-counts:sync:

desc: "Synchronize published format counts with the MIME registry"

cmds:

- python3 scripts/sync_supported_counts.py sync

- alef readme

- task: plugin:generate

supported-counts:verify:

desc: "Test and verify published format counts against the MIME registry"

cmds:

- uv run --frozen --only-dev python -m pytest -q scripts/test_sync_supported_counts.py

- python3 scripts/sync_supported_counts.py verify

verify:feature-parity:

desc: "Check per-target feature aggregates still match `full` (GH#1443)"

cmds:

- python3 scripts/ci/check-feature-parity.py crates/xberg/Cargo.toml

verify:docker-crates:

desc: "Check every workspace member is COPYd, real, and survives .dockerignore"

cmds:

- bash scripts/ci/docker/check-dockerfile-crate-coverage.sh

docs:verify:changelog:

desc: "Check the docs-site changelog carries every release section from CHANGELOG.md"

cmds:

- python3 scripts/ci/check-changelog-sync.py

e2e:generate:

desc: "Generate E2E tests for all languages from fixtures"

cmds:

- alef e2e generate --strict

e2e:build:

desc: "Build all language bindings used by e2e suites (release)"

cmds:

- alef build --release --lang python,node,ruby,php,ffi,go,java,csharp,elixir,wasm,dart,kotlin_android,swift,zig

e2e:all:

desc: "Generate, build, and run all e2e test suites"

cmds:

- task: e2e:generate

- task: e2e:build

- task: e2e:test

e2e:test:

desc: "Run all e2e test suites across all languages"

cmds:

- alef test --e2e --lang rust,python,node,ruby,php,go,java,csharp,elixir,wasm,dart,kotlin_android,swift,zig

e2e:quick:

desc: "Run quick Rust e2e tests"

cmds:

- alef test --e2e --lang rust

e2e:lint:

desc: "Validate e2e fixtures"

cmds:

- alef e2e validate

e2e:verify:

desc: "Verify generated e2e tests are up to date"

cmds:

- alef e2e generate --strict

- git diff --exit-code e2e/

e2e:lang:

desc: "Run e2e tests for a specific language via E2E_LANG variable (e.g., task e2e:lang E2E_LANG=python)"

vars:

E2E_LANG: '{{.E2E_LANG | default "rust"}}'

cmds:

- task: "{{.E2E_LANG}}:e2e"

rust:e2e:

desc: "Run Rust e2e tests via alef"

cmds:

- alef test --e2e --lang rust

python:e2e:

desc: "Run Python e2e tests via Alef"

cmds:

- alef test --e2e --lang python

go:e2e:

desc: "Run Go e2e tests (builds xberg-ffi first)"

cmds:

- alef test --e2e --lang go

node:e2e:

desc: "Run Node/TypeScript e2e tests (builds NAPI module first)"

cmds:

- alef test --e2e --lang node

ruby:e2e:

desc: "Run Ruby e2e tests"

cmds:

- alef test --e2e --lang ruby

php:e2e:

desc: "Run PHP e2e tests"

cmds:

- alef test --e2e --lang php

wasm:e2e:

desc: "Run WASM e2e tests (builds wasm-pack bundle first)"

cmds:

# A RUSTFLAGS set anywhere in the environment REPLACES .cargo/config.toml's

# [target.wasm32-unknown-unknown] rustflags outright -- cargo does not merge the two.

# CI's setup-onnx-runtime action exports a job-wide RUSTFLAGS carrying

# `-C link-arg=-Wl,-rpath,$ORIGIN`, which rust-lld rejects outright, and the override

# simultaneously drops the bulk-memory / getrandom_backend / --allow-multiple-definition

# flags the wasm build needs. Emptying is not enough -- an empty-but-set RUSTFLAGS still

# wins over the config file -- and CARGO_ENCODED_RUSTFLAGS must go too, since it takes

# precedence over RUSTFLAGS when present. Unset here rather than in the workflow so every

# caller inherits it; scripts/ci/wasm/run-crate-tests.sh already had to learn this

# separately for the other wasm entry point. ~keep

- unset RUSTFLAGS CARGO_ENCODED_RUSTFLAGS && alef test --e2e --lang wasm

elixir:e2e:

desc: "Run Elixir e2e tests (compiles NIF first)"

cmds:

- alef test --e2e --lang elixir

java:e2e:

desc: "Run Java e2e tests (builds xberg-ffi first)"

cmds:

- alef test --e2e --lang java

csharp:e2e:

desc: "Run C# e2e tests (builds xberg-ffi first)"

cmds:

- alef test --e2e --lang csharp

dart:codegen:

desc: "Generate flutter_rust_bridge bindings for Dart"

cmds:

- |

command -v flutter_rust_bridge_codegen >/dev/null 2>&1 || \

cargo install flutter_rust_bridge_codegen --version 2.13.0

- cd packages/dart && dart pub get

- cd packages/dart/rust && flutter_rust_bridge_codegen generate --config-file flutter_rust_bridge.yaml

dart:setup:

desc: "Setup Dart binding (codegen + native lib build + post-processing via alef)"

cmds:

- alef build --lang dart --release

dart:e2e:

desc: "Run Dart e2e tests"

cmds:

- task: dart:setup

- alef test --e2e --lang dart

kotlin-android:e2e:

desc: "Run Kotlin/Android e2e tests"

cmds:

- alef test --e2e --lang kotlin_android

swift:e2e:

desc: "Run Swift e2e tests"

cmds:

- alef test --e2e --lang swift

zig:e2e:

desc: "Run Zig e2e tests"

cmds:

- alef test --e2e --lang zig

publish:validate:

desc: "Validate publish manifests are consistent"

cmds:

- alef publish validate

publish:prepare:

desc: "Prepare packages for publishing (vendor deps, stage FFI)"

cmds:

- alef publish prepare

publish:build:

desc: "Build release artifacts for all languages"

cmds:

- alef publish build

publish:package:

desc: "Package built artifacts into distributable archives"

cmds:

- alef publish package -o dist/

php:build:

desc: "Build the xberg-php native extension (cdylib)"

cmds:

- cargo build --locked --release -p xberg-php

python:build:sdist:publish:

desc: "Build the Python sdist using maturin"

dir: packages/python

env:

DIST_DIR: '{{.DIST_DIR | default "../../dist"}}'

cmds:

- mkdir -p "$DIST_DIR"

- maturin sdist --out "$DIST_DIR"

wasm:build:all:

desc: "Alias for rust:wasm:build:all (build all WASM targets + TS wrapper)"

deps: [rust:wasm:build:all]

java:build:release:

desc: "Build the Java binding via Maven (mvn package)"

dir: packages/java

cmds:

- mvn -B -DskipTests package

csharp:build:release:

desc: "Build the C# binding in Release configuration"

dir: packages/csharp

cmds:

- dotnet build --configuration Release

csharp:package:

desc: "Pack the C# binding into a NuGet package (forwards extra args)"

dir: packages/csharp

cmds:

- dotnet pack --configuration Release {{.CLI_ARGS}}

csharp:format:

desc: "Format C# binding with dotnet format"

cmds:

- dotnet format

dir: packages/csharp

csharp:lint:

desc: "Lint C# binding with dotnet format --verify-no-changes"

cmds:

- dotnet format --verify-no-changes

dir: packages/csharp

kotlin-android:format:

desc: "Format Kotlin/Android binding with ktlint via gradle"

cmds:

- gradle ktlintFormat --no-daemon

dir: packages/kotlin-android

kotlin-android:test:

desc: "Run Kotlin/Android binding tests"

cmds:

- cargo build --locked --release -p xberg-ffi

- gradle test --no-daemon

dir: packages/kotlin-android

swift:format:

desc: "Format Swift binding with swift format"

cmds:

- swift format --in-place --recursive Sources

dir: packages/swift

swift:lint:

desc: "Lint Swift binding with swift format lint"

cmds:

- swift format lint --recursive Sources

dir: packages/swift

swift:test:

desc: "Run Swift binding tests"

cmds:

- cargo build --locked --release --manifest-path packages/swift/rust/Cargo.toml

- swift test

dir: packages/swift

dart:format:

desc: "Format Dart binding with dart format"

cmds:

- dart format .

dir: packages/dart

dart:test:

desc: "Run Dart binding tests"

cmds:

- cargo build --locked --release --manifest-path packages/dart/rust/Cargo.toml

- dart pub get

- dart test

dir: packages/dart

zig:format:

desc: "Format Zig binding with zig fmt"

cmds:

- zig fmt src

dir: packages/zig

zig:lint:

desc: "Check Zig formatting with zig fmt --check"

cmds:

- zig fmt --check src

dir: packages/zig

zig:test:

desc: "Run Zig binding tests"

cmds:

- cargo build --locked --release -p xberg-ffi

- zig build test

dir: packages/zig

clean:

desc: "Remove build artifacts across all languages"

cmds:

- cargo clean

- alef clean

- rm -rf coverage.lcov dist/ .alef/