@starci/eslint-canon-fe 4.0.0 → 6.0.0

package/docs/translation.md

@@ -0,0 +1,54 @@
+# 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" }
+const status = { ready: "Your course is ready" }
+<p>{`${count} installed`}</p>
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+<button>{t("save")}</button>
+<input placeholder={t("search")} />
+const o = { title: t("courses.title") }
+```
+
+A template literal with substitutions is copy when its static parts contain a word (`${count} installed`, `You have ${c} unread messages`) in a JSX child, a copy attribute or a copy-key value; class names, URLs, keys, ids, units and format tokens (`btn-${tone}`, `/courses/${id}`, `${n}px`, `YYYY-MM-DD HH:mm`) are not copy. An object property under any key is copy when its value is a whole sentence (two or more words, starting like a sentence, ending like one, or in a non-ASCII script): a hook returning `{ ready: "Your course is ready" }` is a finding.
+
+**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,195 @@
+# Transport, status and wire
+
+Law module: `transport.mjs`. Catalogue: R50 FE_TRANSPORT_OWNER, R51 FE_HTTP_STATUS_COLLAPSE, R52 FE_WIRE_GENERATED.
+
+One repository, one client, one result vocabulary. The client is the file of HFS slot `fe.transport.client` (`apps/<app>/src/modules/api/client.ts`, a one-app repository) or `fe.package.api.client` (`packages/<family>-api/src/client.ts`, the shared client of a multi-app repository); the vocabulary is `Outcome<T>` (`ok`, `refused`, `invalid`, `not-found`, `unavailable`), declared in the `fe.transport.outcome` / `fe.package.api.outcome` file. The rules read the slot of the file being linted, never its path. 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 repository's single `fetch` (and `Request`, `EventSource`, `navigator.sendBeacon`) lives in the api client slot. The global is found by scope resolution: `fetch(...)`, `globalThis.fetch`, `window.fetch`, `self.fetch`, `const f = fetch` and `const { fetch } = globalThis` all count, a local or imported `fetch` does not. A fetch library is refused by module specifier (axios, ky, got, undici, ofetch, graphql-request, urql, `@apollo/*`, ...; `import`, `export ... from`, `import()` and `require`), also inside the client. Another file of the api package (`src/transport.ts`) is not the client.
+
+**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 `Request`, `EventSource`, `sendBeacon`, thư viện HTTP khác) ở `<file>` nằm ngoài client duy nhất (`modules/api/client.ts`, hoặc `src/client.ts` của gói api dùng chung). Mỗi repo chỉ có đúng một đường truyền.
+
+**Cách sửa:** Gọi client của repo 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`
+
+The api client branches on the response status: a comparison of the fetch response's status (typed as a `Response`) with 401 and 403 (`===`, `||`, a literal list `.includes`/`.has`, or a `switch` with both cases) whose consequent builds an object with `kind: "refused"`. The three literals lying anywhere in the file do not pass, and neither does a mapping delegated to a function in another file.
+
+**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 { ok: false, kind: "refused" }
+```
+
+**Finding code:** `FE_HTTP_STATUS_COLLAPSE`
+
+**Vì sao (why):** Client ở `<file>` không có nhánh so sánh `response.status` với 401 và 403 rồi trả `{ kind: "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 `response.status === 401 || response.status === 403` trả `{ ok: false, kind: "refused" }` ngay 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`
+
+A transport response body is narrowed from `unknown` or typed by a generated wire type (a type imported from a `__generated__/` module), never by a hand-written one: `(await response.json()) as unknown` is the sanctioned entry and does not fire; an assertion or annotation of a `.json()` read (directly, or through a `const` initialised with one) to any other type does. Inline GraphQL documents are also refused. A hand-declared interface is not judged by its name; only a response read typed by hand is.
+
+**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"
+const raw = (await res.json()) as unknown
+const x: CourseQuery = parse(raw)
+```
+
+**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`.
+
+## `starci-fe/one-outcome-union`
+
+A result union (`ok` / `kind` discriminant) is declared only in the outcome slot; elsewhere the code composes `Outcome<T>`.
+
+A union type alias is a result union when its resolved members are all object types that carry the same literal-typed discriminant in the result vocabulary: `ok` (each member pins it to one value, `true` and `false` both present) or `kind` (at least one literal of the Outcome vocabulary: `ok`, `refused`, `forbidden`, `invalid`, `not-found`, `unavailable`). The members are read through the type checker, so `Ok<T> | Failure` and intersections are seen as what they are; no name (`*Outcome`, `*Result`) decides anything. UI state unions (`status`, `state`, `type`, a `kind` of tree nodes or menu items) are not result vocabulary and pass; so does an alias that only composes the one union (`type Read = Outcome<Course>`, `Exclude<Outcome<T>, ...>`). `Outcome<T> | { ok: false; kind: "conflict" }` adds an arm to the one union and is refused.
+
+**Invalid** (`src/hooks/invite/useInvite.ts`)
+
+```ts
+export type InviteOutcome = { ok: true } | { ok: false; kind: "refused" }
+```
+
+**Valid** (`src/hooks/invite/useInvite.ts`)
+
+```ts
+import type { Outcome } from "@/modules/api/outcome"
+export type InviteOutcome = Outcome<{ id: string }>
+```
+
+**Finding code:** `FE_HTTP_STATUS_COLLAPSE`
+
+**Vì sao (why):** `<file>` khai báo thêm một union kết quả (`ok` hoặc `kind`) ngoài `outcome.ts`. Repo chỉ có một `Outcome<T>`.
+
+**Cách sửa:** Dùng `Outcome<T>` của `modules/api/outcome.ts` (hoặc gói api dùng chung); thêm chi tiết nghiệp vụ qua tham số thứ hai thay vì khai báo union mới.

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.