Skip to content

QUALITY.md

Latest commit

 

History

History
65 lines (46 loc) · 4.87 KB

QUALITY.md

File metadata and controls

65 lines (46 loc) · 4.87 KB
Raw

Quality at Jolito

Jolito optimizes for fast, safe iteration. We use automation and small, readable changes to move quickly; we do not add process merely to look rigorous.

The quality contract

Every merged code change must pass the automated quality gates:

  • formatting, linting, and strict TypeScript checking;
  • focused unit tests for domain behavior;
  • at least one browser-level test when a user workflow changes;
  • production build;
  • native iOS Xcode compilation and Capacitor sync;
  • dependency vulnerability review (via GitHub Dependency Review on PRs and continuous Dependabot auditing).

CI and supported local development use Node.js >=24 (tested on Node 24 Krypton LTS and Node 26+), pinned to LTS in .nvmrc and GitHub Actions workflows.

The PR author briefly describes behavior changed and verification performed. Screenshots are expected for a material visual change, not for every implementation detail. Human review is for product judgment and design clarity; CI is responsible for repeatable regression detection.

Testing strategy

Layer Purpose Jolito examples
Unit Fast, deterministic domain behavior scheduling, answer comparison, card-direction creation, serialization
Property Invariants across many inputs no invalid review state, stable serialization, valid due-date transitions
Integration Components collaborating in a DOM typing and revealing an answer, a card creation form
Browser/Mobile Critical behavior in real viewports keyboard review loop, mobile touch ergonomics, offline creation
Native CI (iOS) Validate Xcode & Swift compilation xcodebuild workspace verification, Capacitor plugin bindings on macOS-15
Visual Guard the designed experience welcome, create, prompt, revealed answer, mobile breakpoints

Coverage is a guardrail, not a score. The src/domain and src/application core must maintain at least 95% statement, branch, function, and line coverage. UI coverage is judged by behavior-focused integration and browser tests rather than a blanket percentage.

Generalized testing & defect prevention

When writing regression tests for bugs or fixing escaped defects:

  • Generalize beyond the point bug: Tests must aim to generalize beyond a specific bug and catch an entire class of similar bugs. Never write a test that only guards the one line or exact parameter that failed.
  • Hardware & platform round-trip lifecycle contracts: Browser/hardware adapters (Web Audio, Speech Synthesis, WakeLock, Storage Persistence, Service Workers) must be tested against complete round-trip lifecycles (active -> suspended/backgrounded/interrupted -> wake/resume -> active), not isolated entry transitions. Tests must also verify teardown immobility: once destroy() is called, subsequent events or gestures must never revive listeners, timers, or background work.
  • Asynchronous interleaving tests: Core interactive loops (such as active study sessions) must be tested with simulated concurrent interruptions (e.g. background cloud sync reconciliation, token updates, tab visibility changes, or viewport re-orientation mid-session) to verify the queue and active state remain invariant.

Accessibility and performance

Keyboard operation is a core Jolito feature. Every primary workflow must work without a mouse, retain obvious focus, and expose semantic labels. Browser tests run automated accessibility scans for key screens. We will add visual-regression and performance budgets when the first stable product surfaces exist, so the baselines represent intentional design rather than a prototype.

Documentation

Documentation is part of the deliverable:

  • README.md explains what Jolito is and its current user-facing status.
  • docs/PRODUCT_VISION.md records product direction and scope.
  • docs/DESIGN.md defines visual, interaction, and copy principles.
  • docs/ holds developer documentation for architecture, testing, and consequential decisions.
  • Decisions that are costly to reverse require an Architecture Decision Record.

Quality commands

npm run check            # formatting, linting, types, unit coverage, production build
npm run test:e2e         # browser and mobile touch smoke tests
npm run test:db          # pgTAP tests for database migrations, schemas, and RLS policies
npm run lint:db          # lint database schema for typing and syntax errors
npm run test:integration # live integration tests against local Supabase REST/Auth API
npm run cap:sync         # sync web assets to native iOS project
npm run audit:prod       # local production dependency vulnerability audit