Architecture
| Reference |
Value |
| Subject and boundary |
Test layers, the commands that run them, the CI jobs that gate a pull request, the cross-platform generated-byte contract and how to diagnose a failure. Product acceptance is outside this repository. |
| Verified source |
package.json scripts, ci.yml, setup action, Gallery Playwright config, config/playwright, tests/repository at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10, including the merge-queue CI from #200, #201, #203, #204 and #205; ruleset 19092134 read on November 10, 2026. Earlier passes checked 2026-11-09 and November 7, 2026. |
| Support state |
Maintained verification configuration at v0.40.0. Gallery uses Kit 3 and the hook-only navigation lifecycle; the optional adapter is covered by package fake-router tests. |
Test layers
| Layer |
Location and runner |
Proves |
Does not prove |
| Repository |
tests/repository/tooling (release, API and token-cascade tools) and tests/repository/contracts (package manifests and exports, config presets, token artifact ownership, licence notices, workflow SHA pinning); Vitest with vitest.repository.config.ts |
Cross-package and tooling invariants |
Rendered behavior |
| Package unit |
packages/*/src/**/*.test.ts and __tests__; Vitest per package (@yesid/config has none and is covered by repository contracts) |
Neutral package behavior: parsing, generators, contrast, engines, components, state, actions |
Integration in an app |
| Gallery unit |
apps/gallery/tests, apps/gallery/src/**/*.test.ts |
Every public UI family and motion action has an example; UI initialization identity; motion token contract; Gallery gate policy |
Browser behavior |
| Gallery browser |
apps/gallery/tests/browser/*.spec.ts; Playwright on Chromium against a production preview |
Accessibility (axe), keyboard and tap targets, overflow, theme boot, frames, site header, code block, density, runtime |
Released tarballs, other browsers, product routes |
| Product |
Each product's own suites |
Consumer behavior, locale, accessibility, motion and deployment |
(outside this repository) |
Remembered-section verification
The tag's unit contract tests, boot tests and Gallery browser cases cover preference scope, server readability, initial geometry, pending semantics and startup recovery. Review the scenarios at the exact test ref; these source files are not a fresh test-run receipt.
Product adoption checks cover first visit expanded/neutral Collapse all control/open TOC, stored collapse/expand across routes and visits, individual/jump non-writing behavior, threshold and independent-panel exclusions, malformed/blocked storage, another tab, disabled JavaScript, delayed hydration, app-resource failure and five-second stall recovery. Include responsive charts/media, nested fragments, Back and locale reading-position adapters. The pre-paint scanner limits in template, noscript, iframe, xmp, double-escaped script text and --!> comments require the actual mounted count and product layout checks. Source: remembered-sections.md.
Commands
| Need |
Command |
Everything CI's check job runs |
bun install --frozen-lockfile, bun run check, bun run test, bun run ci:tokens, bun run build |
| Types and API |
bun run check: api:check, root tool and repository-test TypeScript, then every workspace check (including svelte-check) |
| All unit tests |
bun run test: the test:changed selection tests (node --test), then the repository suite, then every workspace test through Turbo |
| One package |
bun run --cwd packages/<name> test and check |
| Repository suite only |
bun run test:repository |
| Generated bytes |
bun run ci:tokens |
| Browser suite |
bun run browser:install once, then bun run test:browser (builds the Gallery, then runs Playwright); bun run test:browser:list lists the matrix without building |
| Fast local loop |
bun run test:changed (#204): Vitest --changed against origin/main plus the impacted Playwright specs at one phone and one desktop project. A local accelerator, not a CI gate |
Browser matrix
| Project |
Selects |
Context |
phone, tablet, desktop |
Untagged tests |
390x844 touch, 768x1024 touch, 1440x900 |
reduced-motion |
Tests tagged @motion |
Phone, reduced motion |
light, dark |
Tests tagged @theme |
Desktop, theme seeded through the theme localStorage key |
The Gallery run pins Chromium, en-CA, UTC, reduced motion by default, one worker, no retries, blocked service workers and forbidOnly in CI; traces and screenshots are kept on failure. Specs that assert normal motion opt into no-preference explicitly. Assertions are behavioral; there are no pixel snapshots.
CI gate
flowchart LR
PR["pull_request to main / merge_group / dispatch"] --> CL["classify"]
CL --> CK["check (ubuntu)"]
CL --> BS["browser-shards x3 (Playwright container)"]
BS --> BA["browser-authority"]
CL --> TW["token-outputs-windows"]
CK --> TP["token-byte-parity"]
TW --> TP
CK --> CI["ci (required)"]
BA --> CI
TW --> CI
TP --> CI
| Job |
Steps |
classify |
Runs tools/ci-policy.ts taken from the PR's base SHA, or the merge queue's base SHA; a later queue entry whose base is not yet on main uses main's trusted policy instead of failing. Selects the browser lane unless the PR changes only the root README.md, CONTRIBUTING.md or DECISIONS.md, and marks release-only PRs by exact title and a byte-for-byte reproduction. |
check |
Always runs. Setup with Turbo and Vitest caches; api:approve --base <PR base SHA>; check; test; ci:tokens; upload the four Ubuntu token outputs; turbo run build; on release-only PRs, release:check and packing all eight packages. |
browser-shards |
Three shards (#203), one worker each (two workers broke the sheet drag test), in the Playwright v1.61.1 container pinned by digest, with Bun bootstrapped without APT (#201); test:browser --shard=N/3; uploads a timing file on every run that is not cancelled, and the Playwright report and test results on failure, each kept 7 days. Skipped for docs-only and release-only PRs. |
browser-authority |
Wrapper that requires all three browser shards to succeed. Skipped with them. |
token-outputs-windows |
Cached Windows setup (#203); api:check on Windows, tokens:build, upload the four Windows outputs. Skipped on release-only PRs. |
token-byte-parity |
Byte comparison (cmp) of DESIGN.md, theme.css, motion tokens.ts and tokens.css from both runners; prints both SHA-256 values on mismatch. Skipped on release-only PRs. |
ci |
Runs policy from the PR's base SHA. Fails when a needed job failed or was cancelled, or was skipped outside the lane classify selected. |
The setup action installs Bun from .bun-version and runs bun install --frozen-lockfile with a Bun cache keyed on the OS, .bun-version and bun.lock. Secret scanning and CodeQL run separately (see Security, configuration and supply chain).
Ruleset 19092134 "Protect main" (read 2026-11-10) requires ci and gitleaks (strict up-to-date off) and CodeQL code scanning results, and merges through a merge queue (#200): squash, ALLGREEN, up to 5 entries per group, no wait, 30-minute check timeout, admin bypass always. Org ruleset 26919834 also protects the default branch. Measured 2026-11-10 on #203 (run 42766147239, 3 attempts): execution on the deciding path median 376 to 238 s, slowest browser job 358 to 221 s, Windows job 111.5 to 75 s. Wall time under the throttled runner queue was not proven (attempts took 248 to 2,313 s).
Diagnose a failure
| Symptom |
Investigation and recovery |
api:check drift |
Run bun run api:report and read the diff. Intended: commit the reports with a fragment. Unintended: fix the export or type. |
api:approve fails |
A package's report changed without a new .changes fragment naming it. Add one. |
| API extraction cannot resolve a config |
Check the package tsconfig.json and its extends target and that the frozen install contains @yesid/config. The tooling reports the invalid config before emitting declarations. |
| Token drift or parity mismatch |
Edit tokens.json or the generator, run bun run tokens:build, inspect every changed output. A parity-only failure points at line endings or platform-dependent generator code. |
| Frozen install fails |
First check the pinned Bun version and the manifest/lockfile diff. If Linux CI requires a lockfile change, regenerate with that same Bun on Linux, inspect the diff and rerun. A failure alone is not proof that every lockfile must be generated on Linux. |
| Browser test fails |
Download the failure artifact; rerun the spec with its project, theme and motion setting locally. |
| Gate scan finds zero files |
Wrong root or extensions; an empty scan is not compliance. |
| Packages pass but a product regresses |
Inspect the product's release URLs, lockfile and integration config, then run the product's affected checks. |