mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 09:13:11 +00:00
c96a259365
Some checks failed
Deploy dev content / Deploy shoc-frontend-new-dev through Terraform (push) Has been cancelled
* ci(cd): convert SPA hosting to handbook HCP and GitHub content CD Give HCP the bucket and CloudFront with an empty origin path. GitHub owns bucket-root sync and invalidation so merge-to-main and a human staging tag can deploy without creating HCP runs. G13 fails PRs that mix terraform/ with deployable application files. * ci: run Frontend checks and Terraform CI on PRs to main and dev Match backend 148 so a PR targeting origin/dev still gets the required checks. Push remains main only. * refactor(terraform): keep live/dev and live/staging as HCP roots Leave the adopted working directories in place so this CD PR does not retarget two live HCP workspaces. Flattening stays a later change. * style: prettier terraform-validate.mjs * fix(terraform): pin githubdeploy assume-role policy in import checker Reject controlled role updates whose trust document is not the rendered GitHub OIDC policy, matching the bucket-policy pin.
82 lines
4.2 KiB
Markdown
82 lines
4.2 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`), including G13 app/Terraform isolation. **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).
|