mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 06:53:12 +00:00
4337cc662b
* chore(governance): make React/TS conventions mandatory via executable gates Add AGENTS.md, QUALITY_GATES.md, ARCHITECTURE_AND_CODE_QUALITY.md, and REVIEW_AND_PR_FRAMEWORK.md as the binding conventions and PR review contract for humans and all coding/review agents. Add a single 'npm run verify' command (format + lint + build + test + governance) and 'npm run governance', which runs a dependency-free godfile ratchet (whole-repo, baseline in scripts/governance-baseline.json) and a changed-file maintainability gate (complexity<=20, function<=150, params<=4, depth<=4) via ESLint. Legacy is handled by ratchets, not relaxation: 5 godfiles over 500 lines are grandfathered debt; maintainability thresholds apply to changed TS/TSX (72 legacy violations across ~51 files otherwise). Add a repo-owned 'governance' CI job that runs 'npm run verify' so every gate is guaranteed from this repository, independent of the org reusable workflow. * fix(governance): make frontend ratchets fail closed
81 lines
4.1 KiB
Markdown
81 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).
|