Danijel Martinek
87112c43b0
The previous commit referenced nonexistent files (navigation-repository.contract.ts, tests/get-header.feature.test.ts). The actual contract is header-repository.contract.ts and navigation has no tests/ directory yet. Also adds nav-item.factory.ts to the factories bullet (created in Task 3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# AGENTS.md — navigation
|
|
|
|
Header global for main site navigation. Provides the Header Payload global and tRPC procedures for dynamic navigation content.
|
|
|
|
## What it owns
|
|
|
|
- **Entities** — Navigation type (title, links, menu items)
|
|
- **Use cases** — Get header, update header
|
|
- **Repository interface** — `INavigationRepository` for navigation persistence
|
|
- **Mock repository** — In-memory navigation store for tests
|
|
- **Payload repository** — Real Payload-backed navigation repository (constructor-injected at boot)
|
|
- **Payload global** — Header global definition
|
|
- **tRPC router** — Procedures for get header
|
|
- **DI container** — Per-feature InversifyJS container with navigation symbols
|
|
- **UI components** — Navigation menu, header with branding
|
|
|
|
## Public exports
|
|
|
|
From `package.json`:
|
|
- `.` — Navigation type + UI components (NavigationMenu, Header)
|
|
- `./api` — tRPC router (`navigationRouter`)
|
|
- `./cms` — Payload Header global
|
|
- `./di/bind-production` — `bindProductionNavigation()` to wire Payload repo at boot
|
|
|
|
## What it must NOT import
|
|
|
|
- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
|
|
- Any app package
|
|
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config
|
|
|
|
## Layer rules
|
|
|
|
### `src/` files use relative imports
|
|
|
|
```typescript
|
|
// ✓ Correct
|
|
import type { INavigationRepository } from "../repositories/navigation.repository.interface.js";
|
|
|
|
// ✗ Wrong
|
|
import { Navigation } from "@/entities/navigation.js";
|
|
```
|
|
|
|
### Tests use @/ alias
|
|
|
|
```typescript
|
|
// ✓ Correct
|
|
import { getHeaderUseCase } from "@/application/use-cases/get-header.use-case.js";
|
|
```
|
|
|
|
### DI container is per-feature
|
|
|
|
Tests rebind:
|
|
|
|
```typescript
|
|
import { container as navContainer, NAV_SYMBOLS } from "@/di/container.js";
|
|
import { MockNavigationRepository } from "@/infrastructure/repositories/mock-navigation.repository.js";
|
|
|
|
beforeEach(() => {
|
|
navContainer.unbindAll();
|
|
navContainer.bind(NAV_SYMBOLS.INavigationRepository).to(MockNavigationRepository);
|
|
});
|
|
```
|
|
|
|
## Test conventions
|
|
|
|
- **Unit tests** colocated: `*.test.ts`
|
|
- **Feature tests** in `tests/`: `*.feature.test.ts`
|
|
- **Vitest environment** — `node`
|
|
- **Alias** — `@/` resolves to `src/`
|
|
- **Run** — `pnpm test --filter @repo/navigation`
|
|
|
|
## Tests
|
|
|
|
- **Factories:** `src/__factories__/header.factory.ts` and `src/__factories__/nav-item.factory.ts` — use `headerFactory.build({ overrides })` and `navItemFactory.build({ overrides })` to construct test data with stable defaults.
|
|
- **Contract suite:** `src/__contracts__/header-repository.contract.ts` — runs against every repository implementation (mock + payload).
|
|
- **Unit tests:** colocated as `*.test.ts` next to the source file.
|
|
- **Feature integration:** none today (no `tests/` directory yet); add when a multi-layer flow needs end-to-end coverage.
|
|
|
|
```bash
|
|
pnpm test --filter @repo/navigation # all tests for this feature
|
|
pnpm test --filter @repo/navigation -- --watch # watch mode
|
|
```
|
|
|
|
See `docs/guides/tdd-workflow.md` for the cycle.
|
|
|
|
## Structure (minimal)
|
|
|
|
Per spec addendum v5 ("create folders only when needed"), this feature is small:
|
|
|
|
```
|
|
src/
|
|
entities/
|
|
navigation.ts # Navigation/Header schema
|
|
application/
|
|
repositories/
|
|
navigation.repository.interface.ts
|
|
use-cases/
|
|
get-header.use-case.ts
|
|
infrastructure/
|
|
repositories/
|
|
payload-navigation.repository.ts
|
|
mock-navigation.repository.ts
|
|
di/
|
|
symbols.ts
|
|
container.ts
|
|
bind-production.ts
|
|
interface-adapters/
|
|
controllers/
|
|
navigation.controller.ts
|
|
integrations/
|
|
cms/
|
|
globals/
|
|
header.ts # Payload GlobalConfig
|
|
index.ts
|
|
api/
|
|
router.ts
|
|
index.ts
|
|
ui/
|
|
navigation-menu.tsx
|
|
header.tsx
|
|
index.ts
|
|
tests/
|
|
get-header.feature.test.ts
|
|
```
|
|
|
|
No `application/use-cases/` subdirectory; just one or two use-cases at the top level.
|