@starci/eslint-canon-fe 3.0.2 → 5.1.2

package/docs/spec-quality.md

@@ -0,0 +1,139 @@
+# Spec quality
+
+Law module: `spec-quality.mjs`. Catalogue: R67 FE_SPEC_QUALITY, R60 (real catalogue in specs).
+
+A spec is a claim about one unit's behaviour: no class-string pinning, it imports the unit beside it, no spec for a barrel, no `as unknown as`, an axe assertion for every connected screen, and a real `next-intl` catalogue instead of a mock.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-class-string-in-spec`
+
+A component spec asserts behaviour, never a class string.
+
+**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+expect(el).toHaveClass("bg-primary")
+```
+
+**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+expect(screen.getByRole("button", { name: "Save" })).toBeEnabled()
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` ghim chuỗi class. Spec kiểm hành vi, không kiểm stylesheet.
+
+**Cách sửa:** Assert theo role, tên, trạng thái hoặc chữ hiển thị.
+
+## `starci-fe/spec-tests-its-neighbour`
+
+A spec imports its sibling subject: `X.test.tsx` imports `./X`.
+
+**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+import { Row } from "../Row"
+```
+
+**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+import { Chip } from "./Chip"
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` không import chủ thể nằm cạnh nó.
+
+**Cách sửa:** Đưa spec về cạnh chủ thể, hoặc test đúng đơn vị nằm cạnh.
+
+## `starci-fe/no-barrel-spec`
+
+No `index.test.ts` beside an `index.ts` barrel.
+
+**Invalid** (`src/hooks/index.test.ts`)
+
+```ts
+// file: src/hooks/index.test.ts
+```
+
+**Valid** (`src/hooks/feed/useFeed.test.ts`)
+
+```ts
+// file: src/hooks/feed/useFeed.test.ts
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` đặt cạnh một barrel. Barrel không có hành vi để test.
+
+**Cách sửa:** Xóa spec; test từng đơn vị mà barrel xuất lại, cạnh chính đơn vị đó.
+
+## `starci-fe/no-double-cast-in-spec`
+
+A spec builds its values with the type's own shape, not `as unknown as`.
+
+**Invalid** (`any spec`)
+
+```ts
+const x = { id: 1 } as unknown as Course
+```
+
+**Valid** (`any spec`)
+
+```ts
+const x = mock<Course>()
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` ép kiểu hai lần (`as unknown as`).
+
+**Cách sửa:** Dựng giá trị bằng factory có kiểu (`mock<T>()` hoặc fixture builder).
+
+## `starci-fe/connected-spec-has-axe`
+
+The spec of a connected block or feature runs an axe assertion.
+
+**Invalid** (`src/components/blocks/Feed/index.test.tsx`)
+
+```ts
+it("renders", () => {})
+```
+
+**Valid** (`src/components/blocks/Feed/index.test.tsx`)
+
+```ts
+it("a11y", async () => { expect(await axe(container)).toHaveNoViolations() })
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` của màn hình kết nối không có assert axe.
+
+**Cách sửa:** Thêm `expect(await axe(container)).toHaveNoViolations()`.
+
+## `starci-fe/no-mocked-translations`
+
+A spec renders with the real catalogue; it never mocks `next-intl`.
+
+**Invalid** (`any spec`)
+
+```ts
+vi.mock("next-intl", () => ({}))
+```
+
+**Valid** (`any spec`)
+
+```ts
+render(<NextIntlClientProvider messages={messages} locale="vi" />)
+```
+
+**Finding code:** `FE_I18N_CATALOG`
+
+**Vì sao (why):** Spec `<file>` giả lập `next-intl`, nên chỉ kiểm khóa chứ không kiểm catalog thật.
+
+**Cách sửa:** Render trong `NextIntlClientProvider` với `messages/<locale>.json` thật.

package/docs/translation.md

@@ -0,0 +1,50 @@
+# Translation: no literal copy, no pragma
+
+Law module: `translation.mjs`. Catalogue: R58 FE_I18N_LITERAL.
+
+No text a reader can see or hear is written in source, at any tier and in any language: it is read from a `next-intl` catalogue through `t()`. There is no `vn-ok` pragma, no endonym exemption and no `resources/` copy folder; the catalogues (`messages/<locale>.json`), fixtures and specs are the only content paths. The notion of a literal is the same as nivo-fe's `scripts/check-i18n-catalog.mjs`: a word is two or more letters, and the copy attributes are `label`, `title`, `alt`, `placeholder` and the `aria-*` set.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-copy-resolution-below-block`
+
+The vocabulary tiers receive resolved strings; they never resolve one.
+
+**Invalid** (`src/components/leaves/Input/index.tsx`)
+
+```ts
+const t = useTranslations("input")
+```
+
+**Valid** (`src/components/leaves/Input/index.tsx`)
+
+```ts
+const E = ({ props }) => props.label
+```
+
+
+## `starci-fe/no-hardcoded-copy`
+
+User-facing text comes from a `next-intl` catalogue through `t()`, at every tier.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+<button>Save</button>
+<input placeholder="Search courses" />
+const o = { title: "Your courses" }
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+<button>{t("save")}</button>
+<input placeholder={t("search")} />
+const o = { title: t("courses.title") }
+```
+
+**Finding code:** `FE_I18N_LITERAL`
+
+**Vì sao (why):** Chữ `"<text>"` ở `<file>:<line>` không đi qua `t()`.
+
+**Cách sửa:** Chuyển câu vào `modules/i18n/messages/<locale>.json` và đọc bằng `t("khóa")`; không có ngoại lệ và không có `vn-ok`.

package/docs/transport.md

@@ -0,0 +1,168 @@
+# Transport, status and wire
+
+Law module: `transport.mjs`. Catalogue: R50 FE_TRANSPORT_OWNER, R51 FE_HTTP_STATUS_COLLAPSE, R52 FE_WIRE_GENERATED.
+
+One app, one client (`modules/api/client.ts`), one result vocabulary (`Outcome<T>`: `ok`, `refused`, `invalid`, `not-found`, `unavailable`). 401 and 403 become `refused`; nothing collapses a status into `null`; wire types are generated from the contract copy in `modules/api/contract/`.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/fetch-only-in-api-client`
+
+The app's single `fetch` lives in `modules/api/client.ts`.
+
+**Invalid** (`src/hooks/course/useCourse.ts`)
+
+```ts
+const r = await fetch(url)
+```
+
+**Valid** (`src/hooks/course/useCourse.ts`)
+
+```ts
+const r = await client.get(url)
+```
+
+**Finding code:** `FE_TRANSPORT_OWNER`
+
+**Vì sao (why):** `fetch` (hoặc thư viện HTTP khác) ở `<file>` nằm ngoài `modules/api/client.ts`. Mỗi app chỉ có đúng một đường truyền.
+
+**Cách sửa:** Gọi client của app và nhận `Outcome<T>`; không tự gọi `fetch`.
+
+## `starci-fe/client-fetch-has-signal`
+
+Every `fetch` in `modules/api/client.ts` passes an AbortSignal (timeout or caller).
+
+**Invalid** (`src/modules/api/client.ts`)
+
+```ts
+fetch(url, { method: "GET" })
+```
+
+**Valid** (`src/modules/api/client.ts`)
+
+```ts
+fetch(url, { method: "GET", signal: AbortSignal.timeout(8000) })
+```
+
+**Finding code:** `FE_TRANSPORT_OWNER`
+
+**Vì sao (why):** `fetch` ở `<file>` không có `signal`. Client bắt buộc có timeout và `AbortSignal`.
+
+**Cách sửa:** Truyền `signal` (`AbortSignal.timeout(...)` kết hợp với tín hiệu của người gọi).
+
+## `starci-fe/no-shared-transport-state`
+
+`modules/api/**` holds no module-level `let`/`var`.
+
+**Invalid** (`src/modules/api/client.ts`)
+
+```ts
+let token = null
+```
+
+**Valid** (`src/modules/api/client.ts`)
+
+```ts
+export const request = (token: string) => token
+```
+
+**Finding code:** `FE_TRANSPORT_OWNER`
+
+**Vì sao (why):** `<file>` giữ trạng thái dùng chung dạng `let`/`var` trong tầng API. Token và locale không được nằm trong singleton.
+
+**Cách sửa:** Truyền credential và locale bằng tham số hoặc context.
+
+## `starci-fe/client-maps-auth-to-refused`
+
+`modules/api/client.ts` handles 401 and 403 and produces `refused`.
+
+**Invalid** (`src/modules/api/client.ts`)
+
+```ts
+const r = await fetch(u, { signal })
+```
+
+**Valid** (`src/modules/api/client.ts`)
+
+```ts
+const r = await fetch(u, { signal })
+if (r.status === 401 || r.status === 403) return { kind: "refused" }
+```
+
+**Finding code:** `FE_HTTP_STATUS_COLLAPSE`
+
+**Vì sao (why):** Client ở `<file>` không đổi 401/403 thành `refused`, nên trạng thái "cần đăng nhập" không bao giờ đạt được.
+
+**Cách sửa:** Thêm nhánh 401/403 trả `{ kind: "refused" }` trong client.
+
+## `starci-fe/no-http-status-collapse`
+
+A non-ok response is not folded into one branch or into null; 401/403 become `refused`.
+
+**Invalid** (`src/modules/api/client.ts`)
+
+```ts
+if (!res.ok) return null
+```
+
+**Valid** (`src/modules/api/client.ts`)
+
+```ts
+if (!res.ok) return toOutcome(res.status)
+```
+
+**Finding code:** `FE_HTTP_STATUS_COLLAPSE`
+
+**Vì sao (why):** `<file>` gộp mọi mã HTTP thành một nhánh (hoặc trả null khi phản hồi lỗi). 401/403 phải thành `refused`.
+
+**Cách sửa:** Trả `Outcome` theo mã: `refused` (401/403), `not-found`, `invalid`, `unavailable`; không trả nguyên văn lỗi của server làm lý do.
+
+## `starci-fe/no-hand-typed-wire`
+
+Wire types come from the contract copy via codegen; responses are not cast.
+
+**Invalid** (`src/modules/api/course/read-course.ts`)
+
+```ts
+const x = (await res.json()) as Course
+```
+
+**Valid** (`src/modules/api/course/read-course.ts`)
+
+```ts
+import type { CourseQuery } from "../__generated__/graphql"
+```
+
+**Finding code:** `FE_WIRE_GENERATED`
+
+**Vì sao (why):** `<file>` tự gõ kiểu wire hoặc ép kiểu phản hồi. Dùng kiểu sinh từ `contract/`.
+
+**Cách sửa:** Chạy codegen từ bản sao hợp đồng ở `modules/api/contract/` và nhập kiểu sinh ra; đưa tài liệu GraphQL vào tệp `.graphql`.
+
+## `starci-fe/outcome-kinds-exhaustive`
+
+A `switch` over an Outcome's `kind` has a case for every kind (catalogue R51, sub-check `FE_OUTCOME_KIND_UNHANDLED`).
+
+**Invalid** (`src/hooks/course/useCourse.ts`)
+
+```tsx
+switch (outcome.kind) { case "ok": return outcome.data; default: return null }
+```
+
+**Valid** (`src/hooks/course/useCourse.ts`)
+
+```tsx
+switch (outcome.kind) {
+  case "ok": return outcome.data
+  case "refused": return goToSignIn()
+  case "invalid": return showIssues(outcome.issues)
+  case "not-found": return notFoundState()
+  case "unavailable": return retryState(outcome.retryable)
+}
+```
+
+**Finding code:** `FE_OUTCOME_KIND_UNHANDLED`
+
+**Vì sao (why):** `switch` trên `kind` ở `<file>` có nhánh `ok` nhưng thiếu một trong refused, invalid, not-found, unavailable.
+
+**Cách sửa:** Viết đủ năm nhánh của `Outcome<T>`, mỗi nhánh một màn; không dựa vào `default`.

package/docs/type-safety.md

@@ -0,0 +1,95 @@
+# Type safety
+
+Law module: `type-safety.mjs`. Catalogue: R22 HFS_TS_STRICT, sub-check `FE_TYPE_ESCAPE`.
+
+The compiler is told the truth or it is not told at all. The double cast, the plain assertion, the non-null assertion and `any` are the four spellings of "trust me". `as const`, `as unknown` and `satisfies` stay allowed. Specs are exempt: a test builds values the types forbid, because that is what it proves.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-double-cast`
+
+No cast through `unknown`; it turns checking off at the boundary.
+
+**Invalid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const row = payload as unknown as CourseRow
+```
+
+**Valid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const row = parseCourseRow(payload)
+```
+
+**Finding code:** `FE_TYPE_ESCAPE`
+
+**Vì sao (why):** `<file>` ép kiểu qua `unknown` (`as unknown as T`): trình biên dịch quên mọi thứ nó biết ngay tại chỗ dữ liệu đi vào.
+
+**Cách sửa:** Thu hẹp từ `unknown` bằng type guard hoặc parser; không ép kiểu.
+
+## `starci-fe/no-type-assertion`
+
+No `as T` or `<T>x`; narrow with a check, a guard or a parser.
+
+**Invalid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const row = payload as CourseRow
+```
+
+**Valid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const row = isCourseRow(payload) ? payload : null
+```
+
+**Finding code:** `FE_TYPE_ESCAPE`
+
+**Vì sao (why):** `<file>` dùng `as T` hoặc `<T>x`: một lời khẳng định trình biên dịch không kiểm được. Sai thì lỗi rơi vào trình duyệt của người dùng.
+
+**Cách sửa:** Thu hẹp bằng type guard, `in`, discriminant hoặc parser tại nơi dữ liệu đi vào; dùng `satisfies` nếu chỉ muốn kiểm một literal.
+
+## `starci-fe/no-non-null-assertion`
+
+No non-null assertion (`x!`); prove the value is there.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```tsx
+const first = rows[0]!
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```tsx
+const first = rows[0] ?? fallbackRow
+```
+
+**Finding code:** `FE_TYPE_ESCAPE`
+
+**Vì sao (why):** `<file>` dùng `x!`: khẳng định giá trị có mặt mà không chứng minh.
+
+**Cách sửa:** Xử lý nhánh vắng mặt (`if`, `??`, return sớm) hoặc sửa kiểu để giá trị không thể vắng.
+
+## `starci-fe/no-explicit-any`
+
+No `any`; use a real type or `unknown` and narrow.
+
+**Invalid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const parse = (value: any) => value.id
+```
+
+**Valid** (`src/modules/api/read-course.ts`)
+
+```tsx
+const parse = (value: unknown) => (isCourseRow(value) ? value.id : null)
+```
+
+**Finding code:** `FE_TYPE_ESCAPE`
+
+**Vì sao (why):** `<file>` dùng `any`: tắt kiểm kiểu cho giá trị đó và mọi thứ suy ra từ nó.
+
+**Cách sửa:** Dùng kiểu thật, generic, hoặc `unknown` rồi thu hẹp tại chỗ dùng.