# Code Style Guide

Demeter follows the monorepo's shared TypeScript style, enforced by ESLint +
Prettier (run via `lint-staged` on commit). This guide captures the conventions
that matter most.

## Language & types

- **TypeScript everywhere** by default; reach for Rust/WASM only for
  performance-critical kernels (not applicable to most Demeter code).
- Prefer explicit, descriptive types on public APIs. Avoid `any`; use `unknown`
  - narrowing at boundaries.
- Validate external input with **Zod** at the route boundary; let inferred types
  flow inward.

## Formatting

- **Prettier** is the source of truth — don't hand-format. It runs on staged
  files automatically.
- Note: Prettier relocates trailing comments after `{`; when a comment must stay
  put (e.g. an annotation on an `if (...) {` line), add `// prettier-ignore`
  above it.

## Naming & structure

- Files: `kebab-case.ts`; one cohesive module per file.
- DB layer: `<resource>-store.ts` exposing a `<Resource>Store` class; routes in
  `routes/<resource>.ts` keep Zod + Fastify schemas and delegate persistence.
- Domain objects use **camelCase** with ISO-string timestamps; DB rows use
  `snake_case` (see [data models](../data-models.md)).
- Match the surrounding code's idiom and comment density; write comments that
  explain **why**, not what.

## The stub linter

A custom ESLint plugin + a pre-commit scan reject stub indicators in logic:
`TODO`/`FIXME`, "in production this would…", `Math.random()` standing in for a
computed result, hardcoded returns with excuse comments, and "simulated"
backends. Genuine false positives are suppressed inline with
`// stub:legitimate <reason>` (same line) — see [contributing](contributing.md).

## Fastify plugins

Wrap plugins with `fastify-plugin`, pin `fastify: '5.x'`, and register
cross-cutting concerns in `buildServer()` **before** routes (see
[ADR-0002](../architecture/adr/0002-fastify-plugin-architecture.md)).

## Imports & dependencies

- Use workspace path aliases (`@demeter/*`, `@oshun/*`); no deep relative
  reaches across packages.
- Add dependencies via the pnpm **catalog** (`catalog:` refs) and run
  `pnpm install`.
- No duplicate imports / unused imports — ESLint blocks the commit.
