Skip to content

[CI] Make local, PR, hardware, and release quality gates truthful #140

Description

@proggeramlug

Parent: #126

Problem

The repository's quality contract is fragmented:

  • scripts/ci-check.sh describes itself as local parity but omits several CI/release-sensitive checks;
  • rustfmt/clippy are advisory in .github/workflows/test.yml;
  • example compilation and real browser startup are not a complete matrix;
  • reference validation is report-oriented and not a required gate;
  • FFI and file-size ratchets can fail independently of the command contributors are told to run.

An engine cannot protect high-end rendering work if “green locally” and “green in CI” mean different things.

Outcome

One versioned check manifest/entry point used by local development, PR CI, and release gating, with explicit quick/full/hardware lanes and no ignored required failures.

Design

Single orchestration source

Use one script/tool (the existing scripts/ci-check.sh may evolve) to define named lanes:

  • quick: formatting/lint baseline, unit tests, FFI/schema validation, file ratchets, representative example compile;
  • full: all host builds, shared/web checks, all example compile checks, goldens that can run on the host;
  • web: build/package plus browser startup/render smoke;
  • hardware: quality corpus and GPU/path-tracing cases;
  • release: full plus packaging/install smoke for artifacts.

CI invokes the same lanes rather than reimplementing command lists in YAML. Commands must emit machine-readable summaries and preserve normal console output.

Baselines and rollout

  • Fix existing violations or record a narrow ratcheting baseline with owner/removal issue.
  • continue-on-error is allowed only for a named migration with an expiry/issue; required checks cannot be advisory indefinitely.
  • A test may skip only with a structured reason and the lane declares which skip reasons are acceptable.
  • Dirty worktree diagnostics are reported locally but do not mutate source/baselines.

Required coverage

  • cargo fmt --check and clippy policy for maintained Rust crates;
  • shared unit/integration/golden tests;
  • FFI/schema parity and public API generation freshness;
  • file-size/monolith ratchets;
  • native platform builds available to the runner;
  • WASM check/build and real-browser smoke;
  • compile every canonical TypeScript example against its checked-in package/manifest;
  • release artifact contents/startup, including Windows shader compiler dependencies;
  • quality/hardware lane from the quality harness issue.

Acceptance criteria

  • ./scripts/ci-check.sh --quick (or replacement) runs every PR-required platform-independent check and exits non-zero on any failure.
  • CI YAML delegates to the same named lanes; a test verifies the command inventory cannot silently diverge.
  • No required lint/format/FFI/example check uses continue-on-error or || true.
  • All canonical examples compile in CI; at least one native and one web example reaches and renders a known frame in smoke testing.
  • PR failures upload useful artifacts (golden diffs, browser logs/screenshots, capability report) without requiring rerun access.
  • Release workflow gates the exact tag SHA on required lanes and package-install smoke.
  • A contributor setup section lists tool prerequisites and gives one quick and one full command.

Likely files

  • scripts/ci-check.sh
  • .github/workflows/test.yml, .github/workflows/release.yml
  • tools/validate-ffi.js, tools/check-file-lines.js, quality tooling
  • example package.json files and top-level docs

Non-goals

  • Running expensive GPU qualification on every hosted runner/commit.
  • Reformatting unrelated user work as part of the issue.
  • Treating compilation as sufficient browser/runtime validation.

Dependencies

Can start immediately. Add quality/hardware lane when that child issue lands.

Activity

  1. proggeramlug commented on Jul 28, 2026

    @proggeramlug
    ContributorAuthor

    Implementation checkpoint on draft PR #147:

    • 5c2497f makes scripts/ci-check.sh the named quick, full, web, and hardware entry point used by local development and workflow jobs. A contract test rejects YAML/script drift. Local quick passed 298 unit tests plus 44 golden tests, the WASM check, FFI/schema and line ratchets, quality governance, and bloom-diff.
    • Formatting and clippy correctness/suspicious/performance checks are required. The only clippy allowances are four explicit legacy ratchets; required checks no longer rely on continue-on-error or || true.
    • 7773f70 adds a checked, complete inventory of 20 canonical package/main examples. Ten stale manifests gained their required native-library allowlists, and all 20 pass Perry code generation locally.
    • The web lane performs a real Chrome/Chromium WebGPU boot, submits Bloom's known direct-2D clear frame, waits for queue completion inside a validation scope, captures a compositor screenshot, and validates its blue/green/red channel ordering. Local evidence measured mean RGB (99, 177, 241).
    • Metal and Vulkan quality jobs delegate their quality/fault/corpus work to the same hardware lane components; Metal also runs the canonical example compile gate.
    • aa9d6a0 preserves target/ci, browser logs/screenshots, golden actuals, and quality output for every failed PR job. Run 30343304233 already proved this path by publishing the first hosted-Linux browser diagnosis artifact.
    • 59bdc4a resolves and peels the requested release tag once, requires Tests for that exact commit SHA, checks every release job out at that SHA, and rejects a package-version/tag mismatch.
    • 7407d7c pins headless Linux Chrome to its documented Vulkan/SwiftShader test backend after the first hosted run exposed a swap-chain allocation failure; it also records adapter details in the machine-readable result. Local visual validation remains green; the hosted rerun is in progress.

    Still deliberately open:

    1. I am not checking the combined example/native/web runtime criterion until a hardware-lane archive demonstrates the linked native path as well as the hosted browser rerun.
    2. I am not checking the release criterion yet. Exact-SHA gating is implemented, but npm pack --dry-run confirms the current package contains neither dxcompiler.dll nor dxil.dll; release install/startup smoke must consume the runtime manifest delivered by [Platform] Package shader runtime dependencies and enforce UTF-8 end to end #145.
  2. proggeramlug commented on Jul 28, 2026

    @proggeramlug
    ContributorAuthor

    Hosted validation is now green on a45d3e8 / Tests run 30344662755.

    The diagnostic sequence established a real runner limitation rather than weakening the gate:

    • Ubuntu Chrome could obtain the Google SwiftShader adapter, but its headless compositor could not allocate WebgpuSwapChainTexture shared-image backing.
    • Xvfb did not provide a usable DevTools/presentation path on that runner image.
    • The final workflow keeps the WASM check and optimized package build required on Ubuntu, uploads that exact native/web/pkg artifact, then requires a dependent macOS Chrome job to download it, submit Bloom's known frame, wait for WebGPU completion, capture it, and verify the compositor pixels.

    Final check results: build-web passed in 2m16s and dependent browser-smoke passed in 29s. Every Tests and Renderer quality contract check on the PR head is green. The combined canonical-example/native/web criterion remains unchecked only because its all-example linked native/hardware evidence is still pending; the web half is now proven in hosted CI.

  3. proggeramlug commented on Aug 10, 2026

    @proggeramlug
    ContributorAuthor

    PR #147 required-check repair pushed in 5eee9a6.

    The reported ffi-parity failure was not an FFI mismatch: schema/export parity was green, then the same contracts lane correctly failed the renderer monolith ratchet (renderer/mod.rs 14,669 lines vs 14,649 grandfathered). The fix extracts 598 lines of immediate-mode 3D tessellation into renderer/immediate_draw3d.rs, reducing the monolith to 14,071 lines instead of weakening the baseline. The exact local contracts lane now passes: command inventory, 491-function platform FFI coverage/arity, and file-size ratchet.

    The macOS shared-test failure was a truthful constrained-capability case: the hosted adapter granted 19 sampled textures while the optional layered scene specialization requires 22. The visibility parity test incorrectly required that unsupported specialization to initialize. It now asserts availability from the negotiated granted/required limits, requires initialization exactly when available, and still requires the sheen LUT plus six forward-compatibility layered draws on the fallback. Screenshot and all four MRT parity gates remain mandatory.

    Local evidence: 419/419 shared unit tests, 2/2 visibility-buffer integration tests, 2/2 lit-primitive goldens, and the exact --quick --component contracts lane pass. Remote macOS/Linux/Windows/web/mobile checks are running on the pushed commit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions