ci: shard package tests without weakening coverage gates

[StevenMcClankerton]

Linked issue

n/a — infrastructure change without a Linear ticket.

At a glance

# Package Tests (1/4 ... 4/4)
- run: pnpm coverage:packages --reporter=blob --shard=${{ matrix.index }}/4
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a

# Coverage
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
  with:
    pattern: package-coverage-*
    merge-multiple: true
- run: pnpm coverage:packages:merge
- run: pnpm coverage:report

Package tests now execute on four runners, while a separate Coverage job evaluates thresholds once against the combined native Vitest report. Test Examples runs concurrently, and a lightweight final Test job preserves the required status name.

Summary

The package-test portion of Test was the remaining serial CI bottleneck. This change shards that work horizontally while keeping one authoritative coverage gate and the existing required Test status context.

Decision

This PR ships three connected CI changes:

1. Run package tests and V8 coverage across four native Vitest shards, each uploading one uniquely named blob artifact.
2. Download and require all four blob reports in a separate Coverage fan-in job, merge their coverage counters with Vitest, and only then apply the existing package-level thresholds and warning policy.
3. Run examples concurrently and preserve assertion failures, inert-diff behavior, and the required Test check name through a lightweight final gate.

Reviewer notes

• Shards use SHA-pinned actions/upload-artifact; Coverage uses SHA-pinned actions/download-artifact with pattern: package-coverage-* and merge-multiple: true. Both are GitHub-created actions in the actions organization, so the existing GitHub-actions category permits them without individual allow-list entries.
• Uploads set include-hidden-files: true because Vitest writes blobs below .vitest/blob, and if-no-files-found: error prevents a shard from silently publishing nothing.
• GitHub does not expose artifacts from an earlier workflow attempt to rerun jobs. Use Re-run all jobs, not Re-run failed jobs; a partial rerun fails safely when Coverage verifies the four expected files.
• Coverage thresholds and file reporters are deliberately disabled only in partial shard processes. The merge process runs without the shard marker and therefore restores the complete policy.
• The stable required status remains Test; the four Package Tests (N/4) jobs, Coverage, and Test Examples are implementation details behind its final result.
• The hosted four-runner transport can only execute in GitHub Actions. A local two-shard smoke test proved Vitest's blob names, merged counters, and final-only 100% threshold behavior.

How it fits together

1. vitest.config.ts recognizes shard collection through VITEST_COVERAGE_SHARD, keeps the full include/exclude policy, and suppresses only partial-run thresholds and coverage output.
2. .github/workflows/ci.yml runs vitest --coverage --reporter=blob --shard=N/4 on four PostgreSQL-backed runners. Each shard still reports test failures, uploads exactly one hidden blob file, and explicitly propagates a failing outcome after the upload.
3. Coverage downloads all package-coverage-* artifacts into .vitest/blob and checks for blob-1-4.json through blob-4-4.json before doing any merge.
4. pnpm coverage:packages:merge invokes Vitest's native --merge-reports path, which combines Istanbul counters rather than averaging percentages and replays failed tests.
5. The existing pnpm coverage:report attributes merged source entries to packages and enforces their thresholds. Test Examples runs concurrently, while the final Test job fails if any package shard, coverage, example, or prerequisite job failed.

Behavior changes & evidence

• Package tests execute across four CI runners instead of one. The matrix and fan-in are in .github/workflows/ci.yml, with the expected orchestration locked by scripts/coverage-config.test.mjs.
• Coverage gates see the complete combined run. Shard-aware configuration lives in vitest.config.ts, while the native merge command is declared in package.json and existing package aggregation remains in scripts/coverage-report.mjs.
• Missing shards, assertion failures, and partial reruns cannot silently pass. Unique artifact names, hidden-file uploads, all four required filenames, and the final failure fan-in are asserted by scripts/coverage-config.test.mjs.
• The CI contract is documented for future changes. The rationale and operational flow are recorded in docs/oss/ci-pipeline.md and the package coverage guides.

Testing performed

• pnpm build — 85 tasks passed
• pnpm test:scripts — 498 tests passed
• node --test scripts/coverage-config.test.mjs scripts/coverage-report.test.mjs — 34 tests passed
• pnpm lint:workflows
• pnpm exec biome check vitest.config.ts scripts/coverage-config.test.mjs package.json turbo.json
• pnpm exec turbo run build --dry=json
• Parsed .github/workflows/ci.yml with the installed yaml package
• git diff --check
• Synthetic two-shard Vitest 5 smoke test — generated both expected blob files, merged both source maps, replayed both tests, and passed combined 100% thresholds

Skill update

n/a — internal CI orchestration only; no user-facing CLI, API, configuration, error, or terminology changes.

Alternatives considered

• Use cache transport: cache prefix matching restores only one matching entry rather than all shard outputs, which would require four explicit restores. Cache fallback also suggests cross-attempt reuse that GitHub's artifact model intentionally avoids.
• Merge raw JSON manually: Vitest's blob merger already preserves test failures, project metadata, and Istanbul hit counters, avoiding a custom coverage-merging implementation.
• Apply thresholds in every shard: each shard sees only partial execution, so this would create false failures and would not represent repository coverage.
• Keep the single runner and increase workers: package coverage is already worker-capped to protect PGlite/PostgreSQL stability; horizontal runners improve wall time without oversubscribing one machine.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated.
• The PR title is in TML-NNNN: <sentence-case title> form — n/a, this infrastructure change has no Linear ticket and follows the repository's conventional-title precedent.
• The Skill update section is filled in.

Summary by CodeRabbit

• New Features

  • Package tests now run across four parallel CI shards.
  • Added coverage report merging for sharded test runs.
  • Coverage thresholds are applied after all shard results are combined.
  • Example tests now run as a dedicated CI check.

• Documentation

  • Updated testing and CI guides with the new sharded coverage workflow and command.

• Chores

  • Excluded Vitest cache files from version control.
  • Improved CI checks and diagnostics for incomplete or failed test shards.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 63a1622c-917a-4b0a-88b2-bf7b6923f541

📥 Commits

Reviewing files that changed from the base of the PR and between c3ad493 and 78e3ec1.

📒 Files selected for processing (1)

• docs/oss/ci-pipeline.md

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Package coverage CI now runs four Vitest shards, uploads native coverage blobs as artifacts, and merges them in a dedicated Coverage job. Example tests run separately. The final Test job aggregates package, example, and coverage results.

Changes

Package coverage CI

Layer / File(s)	Summary
Coverage shard configuration .gitignore, package.json, turbo.json, vitest.config.ts, scripts/coverage-config.test.mjs	Vitest reads VITEST_COVERAGE_SHARD, disables shard thresholds and non-blob reporters, and supports coverage:packages:merge. Configuration tests validate these settings.
Package shards and example tests .github/workflows/ci.yml	The workflow runs four package-test shards, uploads each native coverage blob as an artifact, and runs example tests in a separate job.
Coverage merge and Test gate .github/workflows/ci.yml, scripts/coverage-config.test.mjs, docs/Testing Guide.md, docs/onboarding/Testing.md, docs/oss/ci-pipeline.md	The Coverage job downloads and verifies four blobs, merges coverage, and runs coverage reporting. The lightweight Test job requires package shards, examples, and coverage. Documentation describes artifact transport, inert-diff behavior, and the updated action policy.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 78e3e

This change parallelizes package tests while preserving the combined coverage gate and required Test status; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant PackageTests
  participant Vitest
  participant ArtifactStorage
  participant Examples
  participant Coverage
  participant Test
  PackageTests->>Vitest: run four sharded coverage tests
  Vitest->>ArtifactStorage: upload native coverage blobs
  Examples->>Examples: run example tests
  Coverage->>ArtifactStorage: download four coverage blobs
  Coverage->>Vitest: merge coverage and generate report
  Test->>Coverage: require successful coverage result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: sharding package tests while preserving coverage enforcement.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch shard-package-tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@prisma/orm-extension-arktype-json

npm i https://pkg.pr.new/@prisma/orm-extension-arktype-json@30156

@prisma/orm-extension-middleware-cache

npm i https://pkg.pr.new/@prisma/orm-extension-middleware-cache@30156

@prisma/orm-extension-paradedb

npm i https://pkg.pr.new/@prisma/orm-extension-paradedb@30156

@prisma/orm-extension-pgvector

npm i https://pkg.pr.new/@prisma/orm-extension-pgvector@30156

@prisma/orm-extension-postgis

npm i https://pkg.pr.new/@prisma/orm-extension-postgis@30156

@prisma/orm-extension-supabase

npm i https://pkg.pr.new/@prisma/orm-extension-supabase@30156

@prisma/orm-family-mongo

npm i https://pkg.pr.new/@prisma/orm-family-mongo@30156

@prisma/orm-family-sql

npm i https://pkg.pr.new/@prisma/orm-family-sql@30156

@prisma/orm-framework

npm i https://pkg.pr.new/@prisma/orm-framework@30156

@prisma/orm-mongo

npm i https://pkg.pr.new/@prisma/orm-mongo@30156

@prisma/orm-postgres

npm i https://pkg.pr.new/@prisma/orm-postgres@30156

@prisma/orm-sqlite

npm i https://pkg.pr.new/@prisma/orm-sqlite@30156

@prisma/orm-target-mongo

npm i https://pkg.pr.new/@prisma/orm-target-mongo@30156

@prisma/orm-target-postgres

npm i https://pkg.pr.new/@prisma/orm-target-postgres@30156

@prisma/orm-target-sqlite

npm i https://pkg.pr.new/@prisma/orm-target-sqlite@30156

@prisma/orm-toolchain

npm i https://pkg.pr.new/@prisma/orm-toolchain@30156

commit: 7c421ce

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	174.86 KB (0%)
postgres / emit	152.08 KB (0%)
mongo / no-emit	101.09 KB (0%)
mongo / emit	90.95 KB (0%)
cf-worker / no-emit	198.74 KB (0%)
cf-worker / emit	173.36 KB (0%)