# Automated Testing and Quality Gates

Mechanica’s foundation now includes executable checks for the highest-risk planning assumptions: the machine catalogue must stay data-driven, URL-addressable, and safe for viewer controls before real GLB assets are added.

## Commands

- `npm run test:run` — runs the Vitest suite once.
- `npm run test` — starts Vitest in watch mode for local development.
- `npm run typecheck:test` — type-checks tests, scripts, and test configuration.
- `npm run validate:catalogue` — discovers machine arrays exported by registry/data modules and validates catalogue invariants.
- `npm run quality` — runs linting, app type-checking, test type-checking, catalogue validation, tests, and the production build.

## Catalogue Integrity Rules

The catalogue validator enforces hard errors for structural defects that would break routing or viewer state:

- catalogue exports must be arrays of machine records;
- machine ids must exist and be globally unique;
- component ids must exist and be unique within their machine;
- exploded-view vectors, when present, must be finite 3D vectors;
- required blueprint scale must remain at or above the planned 28-machine catalogue.

The validator also reports warnings for authoring gaps that are acceptable during foundation work but should be resolved during modelling/content milestones: missing model paths, placeholder assets, missing descriptions, missing tags, missing components, missing camera presets, and missing animation metadata.

## CI

`.github/workflows/quality.yml` runs the complete `npm run quality` pipeline on pushes to `main` and pull requests. This keeps the repository scaffold honest: future catalogue additions must satisfy the data contract before they can land, and the Vercel build remains protected by the same checks developers run locally.

## Authoring Workflow

When adding a new machine definition:

1. Add the machine to the registry/data module with a stable lowercase id.
2. Add component ids before wiring sidebar visibility, opacity, or exploded-view controls.
3. Run `npm run validate:catalogue` to catch duplicate ids and malformed component metadata.
4. Run `npm run quality` before opening a pull request.