# Contributing to Munch Ease

Thanks for helping make Munch Ease better! This repo aims for a lean, predictable codebase. Please keep changes small, typed, and well‑scoped.

## Core axioms (must follow)

- OpenAPI is the single source of truth for shapes (generated in `src/api/types.ts`).
- The SDK (`src/api/sdk.ts`) is the only data access surface.
- Domain types live in `src/domain/types.ts`; minimal normalization in `src/domain/decoders.ts`.
- No casts (`as`, angle brackets) in app code. Generated files are exempt. Boundary-only normalization allowed.
- No `any`/`unknown` in app code. Prefer precise types, `Pick`/`Omit`, and inference.
- Arrays declared in OpenAPI as required are non-nullable in domain types (e.g., `Meal.recipes` is always an array).
- Disallow runtime type checks in app code (`typeof`, `in`, broad `instanceof`).
  - Acceptable exceptions: DOM event narrowing (e.g., `HTMLInputElement`), error normalization in SDK, env detection.
- CamelCase across `src/`; no snake_case.

## Architecture quick tour

- SDK + decoders boundary
  - `src/api/sdk.ts`: All network calls; returns domain-safe types. Normalize errors via `httpError`.
  - `src/domain/decoders.ts`: Convert date strings → `Date`, normalize arrays, and decode nested structures.
- Domain and DTOs
  - Prefer domain aliases from `src/domain/types.ts` over raw `components['schemas'][...]`.
  - Use discriminated unions for UI shapes where needed (e.g., `Group` has `type: 'product' | 'name'`).
- Composables
  - UI logic in `src/composables/*`. Keep components thin.
- Routing
  - Use helpers from `src/router/helpers.ts` (`parseRouteId`, `parseQueryString`) instead of ad-hoc `typeof` checks.

## Coding guidelines

- Keep changes small and incremental. Write a quick unit test when behavior changes.
- Prefer `computed` over ad-hoc recalculation; avoid prop mutation.
- No ad-hoc mappers. If a slimmer shape is needed, use `Pick`/`Omit` with a descriptive name (e.g., `*Summary`).
- Keep runtime guards in the boundary only. UI assumes decoded, normalized types.

## Tooling

- TypeScript strict; ESLint with type-aware rules; Prettier formatting.
- Tests: Vitest + MSW. Keep tests fast and focused.
- Node 18+ recommended.

## Useful scripts

```bash
npm run serve       # Dev server
npm run test        # Unit tests (Vitest)
npm run lint        # ESLint
npm run typecheck   # TS + vue-tsc
npm run build       # Production build
```

## PR checklist

- [ ] Types first: no casts in app code, no `any`/`unknown`
- [ ] Boundary-only normalization in decoders/SDK
- [ ] Arrays reflect OpenAPI nullability in domain types
- [ ] No new mappers; use domain aliases or `Pick`/`Omit`
- [ ] Tests updated/added if behavior changed