Contributing to Jaiph

Contributor docs answer a narrow question: where changes belong, how to run the same checks CI runs, and which test layer should encode a behavior change.

At a high level, Jaiph is built as described in Architecture — transpile path (emitScriptsForModule, buildScripts), parse-only buildRuntimeGraph(), jaiph compile (validate-only), NodeWorkflowRuntime, artifact layout, and Docker helper contracts. Treat that page as authoritative for pipelines and boundaries; if anything here diverges from it or from the implementation, prefer architecture + source.

For workflow syntax, library usage, tooling setup, and grammar details, see Language, Setup, Grammar, and the overview in Getting Started.

Branching and pull requests

Development moves quickly and may include breaking changes. Two primary branches: main (stable) and nightly (latest).

• If you want to fix a bug, point your PR to the main branch, and check if the issue has already been addressed in nightly.
• If you are adding a new feature, submit your PR to nightly (and add or update tests in e2e/tests).
• For non-trivial bugs or features, open an issue with enough context to prioritize and discuss before or alongside a PR.
• AI-assisted pull requests are welcome as long as they include comprehensive tests (including in e2e/tests).

Installing from source

Use the local installer wrapper script in this repo:

./docs/install-from-local.sh

After install, verify:

jaiph --version
jaiph --help

The script installs from local source (including uncommitted changes) and places the CLI in ~/.local/bin by default (or JAIPH_BIN_DIR if set).

Developing in the repository

For day-to-day work on the compiler and CLI you usually stay inside the clone: install dev dependencies once, then build and run tests from npm scripts.

Prerequisites: Node.js 20.x and npm (same setup-node version as .github/workflows/ci.yml). The installers also expect git and bash. End-to-end tests are written in bash and are run by e2e/test_all.sh.

Typical commands (from the repo root):

Run a single Node test file after a build with e.g. node --test dist/src/parse/parse-core.test.js. The dist/ paths mirror the source layout under src/.

Workspace hygiene

The root .gitignore blocks common debug and temp directory patterns so they never reach version control:

If you create throwaway directories during development, use one of these prefixes so they are automatically ignored. To track a file that matches a blocked pattern, use git add -f.

Code philosophy

Jaiph’s codebase is maintained by both humans and AI agents. Code should be easy to read, navigate, and modify for both — which means the same thing: straightforward, flat, and explicit.

Principles

1. Plain functions with explicit arguments. Avoid classes and abstraction-heavy generics. If a file already uses generics, follow the local style and keep additions minimal. No visitor patterns or dependency injection. A function takes data in, returns data out, or pushes to an array. If you need shared context, pass a plain object — not a class instance.
2. Flat control flow. If/else chains and switch statements, not multi-layer abstractions. An AI (or human) should be able to read a function top-to-bottom and understand what it does without jumping to 3 other files.
3. Short files. No source file should exceed ~400 lines. If a file grows past that, split it into sibling files in the same directory — not a deeper module tree.
4. No duplication across files. If the same logic exists in two places, extract it into one plain function and call it from both. Duplication means bug fixes get applied in one place and missed in the other.
5. Minimal touch surface for new features. Adding a new step type, CLI command, or runtime feature should require changes in at most 3 files (type definition, parser/handler, emitter/consumer). If it requires more, the architecture needs refactoring first.
6. No speculative abstractions. Don’t add indirection, registries, or plugin systems to “support future extensibility.” Add the simplest thing that works now. Refactor when the concrete need appears.
7. Red flag: >100 lines of custom code. Before writing a large chunk, check if the library or existing codebase already provides it. If not, explain why the new code is necessary.

Testing philosophy

Jaiph uses several test layers. Each layer catches a different class of bug. Use the narrowest layer that covers the behavior you’re verifying.

Key principles

1. Compile-time validation vs graph loading. buildScripts / emitScriptsForModule run validateReferences before any script files are written. buildRuntimeGraph() only parses modules and follows imports — it does not re-run that validation. Lock compile errors in the compiler/validator tests; the runtime graph is the wrong layer for that (see Architecture — Core components). jaiph compile runs validateReferences only (no buildScripts, no runner); cover it with txtar/acceptance/E2E such as e2e/tests/109_compile_command.sh, not by expecting the full transpile path — see Architecture — System overview.
2. jaiph test vs live events. jaiph test reuses NodeWorkflowRuntime with suppressLiveEvents: true so __JAIPH_EVENT__ lines are not written to stderr alongside node --test output while run_summary.jsonl and other artifact paths stay consistent where the harness writes them (Architecture — Test runner integration).
3. Tests are behavior contracts. E2E tests and acceptance tests define what the product does. Default approach: change production code to satisfy tests, not the other way around.
4. Modify existing tests only with a strong reason: intentional product behavior change, incorrect test expectation, or removal of an obsolete feature. Any such change should be minimal and paired with a clear rationale.
5. Golden tests are the compiler’s safety net. After transpiler changes, run npm test. Failures in src/transpile/compiler-golden.test.ts usually mean updating an explicit expected string or fixture in that file — there is no separate dump script; align expectations with intentional emitter changes and re-run npm test. Golden AST tests (test-fixtures/golden-ast/) complement this by locking in the parse tree shape — if those fail, regenerate with UPDATE_GOLDEN=1 npm run test:golden-ast and review the diff.
6. E2E tests assert two things independently: what the user sees (CLI tree output via e2e::expect_stdout) and what the runtime persists (artifact files via e2e::expect_out, e2e::expect_file). A bug could break one without the other.
7. Prefer the narrowest test layer. A pure function bug should be caught by a unit test, not an E2E test. E2E tests are expensive to run and hard to debug — reserve them for integration-level behavior.

TypeScript test layout

• Module tests — live next to the source they validate under src/ (e.g. src/parse/parse-core.test.ts, src/cli/run/display.test.ts, src/transpile/compiler-golden.test.ts). Names are *.test.ts or *.acceptance.test.ts.
• Integration tests — span multiple modules or need subprocess/PTY harnesses; they live in integration/ (see Integration tests).
• E2E — bash scripts in e2e/tests/*.sh, driven by e2e/test_all.sh.
• npm test discovers colocated files under src/, integration tests under integration/, and test infrastructure in test-infra/; see the Developing in the repository table for the exact command.

Module test layout (colocated)

Module tests live next to the source files they validate, inside the same src/ tree. Names are *.test.ts or *.acceptance.test.ts. To list them from the repo root:

find src -type f \( -name '*.test.ts' -o -name '*.acceptance.test.ts' \) | sort

Grouping (use the find output as authoritative after refactors):

When adding a new source module or extending an existing one, create or extend the corresponding *.test.ts in the same directory. For kernel internals, the compile path, and artifact contracts, see Architecture.

Integration tests

Tests that span multiple modules, require subprocess/PTY harnesses, or exercise process-level behavior live in integration/. These do not belong to a single module:

The integration/sample-build/ directory also has a shared helpers.ts module used by the sample-build tests. Shared test fixtures (.jh source files and expected output) live in test-fixtures/sample-build/.

CI pipeline

The project uses GitHub Actions (.github/workflows/ci.yml). The workflow defines six jobs; on a typical feature-branch push, five of them run. The sixth — Publish Docker runtime image — runs only on pushes to nightly and on v* version tags, after the other jobs succeed. It builds and pushes ghcr.io/jaiphlang/jaiph-runtime (the default runtime.docker_image / JAIPH_DOCKER_IMAGE when Docker sandboxing is on; see Docker runtime helper in Architecture).

Version tags and npm

Pushing a v* ref does not run any npm publish step from this repository: the automation checked in under .github/workflows/ is ci.yml (push CI) and nightly-engineer.yml (optional manual engineer run) — neither publishes to npm. The same tag pattern does satisfy the if: on the docker-publish job in ci.yml, which pushes ghcr.io/jaiphlang/jaiph-runtime after the other CI jobs succeed.

If you are preparing a release that includes the npm package, coordinate version bumps, registry publish, and smoke checks with the maintainers — that flow is intentionally outside this repo’s workflows.

Local docs site (Jekyll)

The Getting started (local) CI job validates that the documentation site under docs/ can be built and served from source. It uses Ruby 3.2 with bundler-cache, runs bundle exec jekyll serve --host 127.0.0.1 --port 4000 in the background, and polls http://127.0.0.1:4000/ for up to 30 seconds before asserting HTTP 200 on /, /getting-started, /setup, /libraries, and /artifacts. The same job also prepares Node, a local jaiph-ci-runtime:local image, Playwright Chromium, and (for samples that need them) external CLIs — see the docs-local job in .github/workflows/ci.yml for the exact package list, which can change.

To run the same check locally:

cd docs
bundle install          # first time only
bundle exec jekyll serve --host 127.0.0.1 --port 4000
# In another terminal:
curl -fsSL http://127.0.0.1:4000/

The Jekyll project lives entirely inside docs/ — Gemfile, _config.yml, layouts, and all Markdown pages.

Landing-page sample verification (Playwright)

After the Jekyll smoke-check, the CI job also verifies that code samples shown on the landing page match real CLI behavior. This uses Playwright (Chromium) with a test suite in e2e/playwright/landing-page.spec.ts.

The test does two things:

1. Source parity — extracts each sample’s source code from the DOM ([data-sample-source] elements inside [data-sample] tab panels) and compares it byte-for-byte against the corresponding file in examples/ (identified by data-sample-file).
2. Output verification — for each [data-sample-output] block whose sample/output key is not listed in SKIP_OUTPUT (e2e/playwright/landing-page.spec.ts), the test parses the ➜ command line, runs it against the temp copy of the page source (the executable .jh from examples/ named by data-sample-file, with say_hello.test.jh also copying companion say_hello.jh), and compares normalized CLI output to the block. Normalization mirrors e2e::normalize_output (ANSI, durations, <agent-command> / <script-path>, log/summary/out/err path lines collapsed to <path>, spacing before ✓ PASS). Entries in SKIP_OUTPUT mark nondeterministic model or agent-backed tabs (e.g. say-hello / success, async / run, recover-loop / run).

To run locally:

npm run test:samples

If a Jekyll server is already running on http://127.0.0.1:4000, Playwright reuses it (reuseExistingServer in playwright.config.ts). Otherwise it starts one.

Samples whose rendered output embeds nondeterministic model or agent transcripts skip output comparison per-tab via SKIP_OUTPUT in e2e/playwright/landing-page.spec.ts (see Landing-page sample verification); those tabs still participate in DOM source parity.

E2E testing

The E2E test suite (e2e/tests/*.sh) drives the toolchain from outside the TypeScript harness: e2e::prepare_test_env (via prepare_shared_context in e2e/lib/common.sh) prepends a jaiph shim to PATH (preferring dist/src/cli.js when built), sanitizes stray JAIPH_* vars, wires JAIPH_REPO_URL to the cloned tree, exports JAIPH_DOCKER_ENABLED=false by default, then each script invokes jaiph run; Docker-specific assertions set JAIPH_DOCKER_ENABLED=true and expect JAIPH_DOCKER_IMAGE (for example jaiph-ci-runtime:local on the CI e2e docker matrix leg). Scripts assert on both the CLI tree (e2e::expect_stdout) and *.out / .err / run_summary.jsonl under .jaiph/runs/ — see also Architecture — Durable artifact layout.

Some scripts are contract tests: they validate persisted machine-readable output (for example e2e/tests/88_run_summary_event_contract.sh and run_summary.jsonl) in addition to or instead of golden CLI trees.

E2E philosophy: two surfaces and full equality

E2E tests are the outermost behavior contracts for the CLI and runtime. Each test should exercise the real pipeline and assert on two independent surfaces:

1. CLI tree output — what the user sees (e2e::expect_stdout with a heredoc).
2. Run artifacts — what the runtime persists under .jaiph/runs/<date>/<source>/ (e2e::expect_out, e2e::expect_file, e2e::expect_run_file). Inbox files live under the run directory when the feature touches inbox behavior.

Default contract: every assertion should compare the full expected text (stdout heredoc, artifact file contents, JSONL lines) unless there is a documented exception. Use e2e::expect_stdout, e2e::expect_out, e2e::expect_file, e2e::expect_run_file, or e2e::assert_equals / e2e::assert_output_equals for full comparisons.

e2e::assert_contains (substring check) is allowed only when full equality is not feasible. Every such use must have an inline comment explaining why. Valid reasons:

• Nondeterministic output — e.g. prompt transcripts with real agent backends, timestamps not covered by <time> normalization.
• Unbounded or variable-length logs — e.g. run_summary.jsonl with platform-dependent event counts, or live step output where line count varies.
• Platform-dependent text — e.g. OS-specific error messages, paths that differ across CI environments.

Normalization: e2e::normalize_output (in e2e/lib/common.sh) strips ANSI codes, replaces timing values with <time>, normalizes __inline_<hash> script names to __inline_<id>, swaps some CLI-specific strings (<agent-command>, <script-path>), and sorts a class of async progress lines (UTF-8 subscript markers) so strict equality stays stable when parallel branches finish in different orders. This keeps full-equality heredocs usable across machines.

Where files land on disk (directory tree, sequence prefixes): Architecture — Durable artifact layout. Runtime testing with *.test.jh is covered in Testing. The run_summary.jsonl event contract is exercised in e2e/tests/88_run_summary_event_contract.sh.

Test structure

Every E2E test follows a Given / When / Then pattern using helper functions from e2e/lib/common.sh. The helpers eliminate boilerplate so each test reads like a specification:

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
source "${ROOT_DIR}/e2e/lib/common.sh"
trap e2e::cleanup EXIT

e2e::prepare_test_env "my_test"
TEST_DIR="${JAIPH_E2E_TEST_DIR}"

e2e::section "Feature under test"

# Given — create the workflow file inline (script + workflow; same shape as e2e/tests/10_basic_workflows.sh)
e2e::file "hello.jh" <<'EOF'
script hello_impl = `echo "hello-jh"`
workflow default() {
  const msg = run hello_impl()
  return "${msg}"
}
EOF

# When — run workflow (`jaiph` transpiles and executes inside the shim)
hello_out="$(e2e::run "hello.jh")"

# Then — assert on CLI tree output (include workflow return value when default() returns one)
e2e::expect_stdout "${hello_out}" <<'EOF'

Jaiph: Running hello.jh

workflow default
  ▸ script hello_impl
  ✓ script hello_impl (<time>)
✓ PASS workflow default (<time>)

hello-jh
EOF

# Then — assert on run artifacts
e2e::expect_out_files "hello.jh" 2
e2e::expect_out "hello.jh" "hello_impl" "hello-jh"

When you need a specific sequence-prefixed filename (e.g. 000002-module__step.out), use e2e::expect_run_file — see e2e/tests/72_docker_run_artifacts.sh and similar.

Helper reference

All helpers are defined in e2e/lib/common.sh.

Setup and lifecycle helpers

File and run helpers

Tree output assertions

Run artifact assertions

After a workflow runs, its step outputs are written as sequenced artifact files under .jaiph/runs/. These helpers verify artifact content independently from CLI display output. For the on-disk layout and naming scheme, see Architecture — Durable artifact layout.

Low-level assertions

Assertion policy

Quick reference: default to full-equality helpers (e2e::expect_stdout, e2e::expect_out, e2e::expect_file, e2e::expect_run_file, e2e::assert_equals). e2e::assert_contains is the exception — every use needs an inline comment; rationale list in E2E philosophy above. Audit substring usage:

rg 'e2e::assert_contains' e2e/tests -n

Orphan sample guard

Every .jh and .test.jh file under e2e/ must be referenced by at least one test script (e2e/tests/*.sh, e2e/test_all.sh, or e2e/lib/). Unreferenced samples confuse contributors, hide drift from the canonical examples/ corpus, and make it unclear which fixtures are load-bearing.

The guard script e2e/check_orphan_samples.sh detects orphans automatically. It scans every .jh and .test.jh file under e2e/, checks whether its basename appears in any test runner or helper, and also resolves indirect references (a file imported by another .jh that is itself referenced counts as covered). Any file that is neither directly nor indirectly referenced is reported as an orphan.

# Run manually from the repo root
bash e2e/check_orphan_samples.sh

On success the script prints OK: no orphan e2e samples detected. and exits 0. On failure it lists the unreferenced filenames and exits 1, with guidance to either wire them into a test, move them to examples/, or delete them.

When adding a new .jh fixture to e2e/, make sure it is exercised by a test in e2e/tests/ or imported by a file that is. If a sample exists purely for documentation or demonstration purposes, it belongs in examples/ instead.

Example matrix guard

Every .jh and .test.jh file under examples/ must be accounted for in e2e/tests/110_examples.sh. The script maintains three arrays that together form the example matrix:

An orphan guard at the bottom of the script fails CI if any example file is not listed in one of the three arrays. To add a new example:

1. Place the .jh file in examples/.
2. Add it to COVERED_RUN, COVERED_TEST, or EXCLUDED (with a comment).
3. If covered, add a test section with strict e2e::expect_stdout and artifact assertions.