Distribution integration testing & artifact verification

[yamcodes]

Status

Proposed

Summary

Introduce a new class of tests that validate ArkEnv’s built artifacts (dist/) and real-world installation behavior, ensuring correctness when optional peer dependencies, subpath exports, and bundling are involved.

Motivation

ArkEnv relies on:

• Optional peer dependencies (e.g. arktype)
• Bundled distribution artifacts
• Subpath exports (arkenv/arktype)
• Plugin consumers (Vite, Bun, etc.)

Certain failures only surface after bundling and outside the monorepo, but are currently invisible to our test suite, which primarily targets src/ with Vitest’s module resolution.

Concrete issues this RFC addresses:

1. Path resolution mismatches between src/ and dist/
2. Peer dependency masking in monorepo test environments
3. Accidental eager imports of optional dependencies in built output
4. Export map regressions that only affect consumers

These risks increase as we approach a production-ready v1.

Proposal

Add Distribution Integration Tests as a first-class testing category.

1. Dist-Targeted Tests

Run a subset of tests directly against the built output.

• Goal: Validate that dist/ behaves exactly as published.
• Approach:
  • Add a test:dist script that imports from dist/index.js
  • Avoid src/ aliases in these tests
• Catches:
  • Broken relative paths
  • Incorrect subpath exports
  • Runtime-only failures

2. Example Project Fixtures (Package-Level E2E)

Formalize examples/ as installation-level integration fixtures.

• Goal: Test ArkEnv as a real dependency.
• Approach:
  1. pnpm pack the current workspace
  2. Install into an example project
  3. Run the example’s entry script
  4. Assert on stdout/stderr
• Use cases:
  • With vs without optional peers
  • Framework-specific integrations (Vite, Bun, etc.)

3. Artifact Verification (Static Analysis)

Add lightweight checks on the built files.

• Goal: Enforce invariants on the published artifact.
• Checks:
  • No top-level import / require("arktype") in main entry
  • Optional dependencies remain lazy
  • Bundle size regression detection (smoke-level)

Relationship to Existing Testing Strategy

Category	Scope	Status
Unit Tests	Pure logic	Existing
Integration Tests	Validator behavior	Existing
Distribution Tests	Built artifact behavior	New
Example / Fixture Execution	Real consumer installs	New

These tests complement, not replace, existing coverage.

Non-Goals

• Replacing source-level tests
• Introducing heavy E2E frameworks
• Testing framework internals (handled by plugin-specific suites)

Implementation Plan

1. Add packages/arkenv/test/dist.test.ts importing from dist/
2. Add a root test:e2e:package script using an example fixture
3. Update TESTING.md to document Distribution Testing
4. Apply the same pattern to @arkenv/*-plugin packages as needed