mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 05:43:12 +00:00
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
|
# AGENTS.md — frontend mandatory conventions
|
|||
|
|
|
|||
|
|
This file is the binding entry point for **every contributor — human or AI coding
|
|||
|
|
or review agent** — working in this repository (`seahaven-new-app`, the SHOC
|
|||
|
|
frontend). It makes the validated React/TypeScript conventions mandatory and
|
|||
|
|
points to the operational documents and executable gates that enforce them.
|
|||
|
|
|
|||
|
|
Read these before writing or reviewing code. They override generic "best
|
|||
|
|
practice" suggestions from any agent or model. This repository contract may
|
|||
|
|
strengthen, but never weaken, the workspace-level `AGENTS.md`.
|
|||
|
|
|
|||
|
|
- [QUALITY_GATES.md](QUALITY_GATES.md) — the executable gates, the single
|
|||
|
|
command, and the no-false-pass guarantees.
|
|||
|
|
- [ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md) — the
|
|||
|
|
MUST / MUST NOT conventions (conditional rendering, typography, forms, state,
|
|||
|
|
data access, security, maintainability) with evidence and thresholds.
|
|||
|
|
- [REVIEW_AND_PR_FRAMEWORK.md](REVIEW_AND_PR_FRAMEWORK.md) — the PR review
|
|||
|
|
contract (exact-head review, board regression inventory, behavior-based
|
|||
|
|
testing, security/performance/Big-O review, no style-only comments).
|
|||
|
|
- [docs/FRONTEND_MAINTAINABILITY.md](docs/FRONTEND_MAINTAINABILITY.md) — the
|
|||
|
|
detailed rationale for the conditional-rendering and typography rules.
|
|||
|
|
|
|||
|
|
## One command to run every gate
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm run verify
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
This chains the full set: Prettier check, ESLint (`--max-warnings=0`), TypeScript
|
|||
|
|
build (`tsc -b && vite build`), unit tests (`vitest run`), and the governance
|
|||
|
|
checks (`npm run governance`). **Do not claim a task is done until `npm run
|
|||
|
|
verify` is green locally.** CI runs the same `npm run verify` in a repo-owned
|
|||
|
|
`governance` job, so a green local run mirrors CI.
|
|||
|
|
|
|||
|
|
## Non-negotiable rules (enforced; do not work around)
|
|||
|
|
|
|||
|
|
These are already enforced by lint/build or the governance script. Disabling,
|
|||
|
|
baselining, or per-line-suppressing them is forbidden (see exceptions below).
|
|||
|
|
|
|||
|
|
- **No one-sided `cond ? <Element/> : null`** — use `&&` or the `when` prop.
|
|||
|
|
- **The left operand of `&&` in JSX must be entirely boolean** — coerce with
|
|||
|
|
`Boolean(...)` / an explicit comparison; `{count && ...}` is rejected.
|
|||
|
|
- **Shared `Text` for `p` / `h1`–`h6` / error typography** — raw `<p>`/`<h*>` and
|
|||
|
|
the `vp-error` class outside `Text` are rejected.
|
|||
|
|
- **Zero lint warnings** — `--max-warnings=0` makes a warning a failure; fix it,
|
|||
|
|
do not silence it.
|
|||
|
|
- **Hooks correctness** — the `react-hooks` recommended rules (including
|
|||
|
|
`exhaustive-deps`) run under the zero-warnings gate.
|
|||
|
|
- **Godfile ratchet** — no source file may exceed 500 lines. Existing named debt
|
|||
|
|
has a frozen per-file cap that may only decrease.
|
|||
|
|
- **Changed-file maintainability** — changed TS/TSX must meet
|
|||
|
|
`complexity ≤ 20`, function `≤ 150` lines, `≤ 4` params, `≤ 4` depth.
|
|||
|
|
|
|||
|
|
## How to add / change a convention
|
|||
|
|
|
|||
|
|
1. Land it **green**: a new or tightened rule must ship with the codebase passing
|
|||
|
|
it (a migration in the same change), not as a warning-only backlog.
|
|||
|
|
2. If legacy would break, use changed-file enforcement or migrate it. Do not add
|
|||
|
|
new baseline debt or raise a frozen cap.
|
|||
|
|
3. Document the rule, its threshold, and its evidence in
|
|||
|
|
[ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md).
|
|||
|
|
|
|||
|
|
## Exceptions and the ADR process
|
|||
|
|
|
|||
|
|
Exceptions are **not granted by disabling a rule inline**. To deviate:
|
|||
|
|
|
|||
|
|
1. Record an **Architecture Decision Record** under `docs/adr/`
|
|||
|
|
(`NNNN-title.md`: context, decision, consequences, alternatives).
|
|||
|
|
2. Existing grandfathered entries may only be removed or have their caps
|
|||
|
|
reduced. New entries and cap increases fail the governance gate.
|
|||
|
|
3. Get it reviewed like any other change. The ADR + baseline entry is the
|
|||
|
|
auditable record; an `eslint-disable` comment is not.
|
|||
|
|
|
|||
|
|
## Toolchain (do not change without an ADR)
|
|||
|
|
|
|||
|
|
React 19, TypeScript 6, Vite, Tailwind 4 + MUI, TanStack Query, React Hook Form +
|
|||
|
|
Zod, Ky. Node ≥ 22.22.1 (CI runs Node 24); npm 11.16.0 (pinned via
|
|||
|
|
`packageManager`, invoked through corepack). **No new dependencies without an
|
|||
|
|
ADR** — prefer the libraries already established (see
|
|||
|
|
[ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md) §Forms and
|
|||
|
|
data access).
|