@starci/eslint-canon-fe 6.0.1 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 7.0.0 - 2026-09-30
+
+- **New: `no-vietnamese-in-source` (R91).** Identifiers, string literals, template text, JSX text, comments and test titles carry no Vietnamese letter, specs included. Detection is structural on characters (`scripts/lib/language.mjs` in `runtime/`, folded to NFC, so NFD is caught too). The only exemption is the i18n fixtures slot `fe.e2e-support.i18n` (`e2e/fixtures/i18n/`). Removed: the second-language branches of `no-hardcoded-copy` (its `second` and `comment` messages) and the `SECOND_LANGUAGE_LETTER` export; the one rule holds the law.
+- **Breaking: the front end has no tests, so the front-end test rules are gone.** Removed rules: `no-class-string-in-spec`,
+  `spec-tests-its-neighbour`, `no-barrel-spec`, `no-double-cast-in-spec`, `connected-spec-has-axe`, `no-mocked-translations`
+  (spec quality), `e2e-spec-location`, `e2e-no-absolute-path`, `e2e-no-docker`, `e2e-no-cross-repo-write`, `e2e-no-skip`,
+  `e2e-typed-helpers`, `playwright-viewports` (e2e shape) and `unit-test-colocated`, with their why entries, docs and fixtures.
+  The factory no longer builds an e2e block (`e2e/**`, `playwright.config.ts`) and returns the ignore block and the typed source block
+  only; `sourceRecommended` and `e2eRecommended` are gone (`recommended` is the one set); the spec and e2e exemptions of the other
+  rules (`isSpecFile`, `isE2eSource`, the `e2e` tier) are deleted. A test file, a test-tool file or a test dependency in a
+  front-end repository is now refused by `hfs check` (FE_NO_TESTS, R97) instead.
+
+## 6.0.2 - 2026-09-30
+
+- **Fix: `use-client-only-at-boundary` refused the providers wrapper.** The route tree's `providers.tsx` (root or `[locale]`,
+  role `providers` of `fe.route` in the slot manifest) is the client component a server layout renders around its children to host
+  context providers; the directive is accepted there. A providers wrapper kept elsewhere (a layout feature, a module) is still a
+  finding, and the message names `providers.tsx` as its home.
+
 ## 6.0.1 - 2026-09-30
 
 - **Fix: `no-hand-rolled-polling` refused a shared clock.** A timer is polling only when what it runs reads data - a call whose

package/README.md

@@ -15,7 +15,7 @@ import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
 export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
 ```
 
-`loadHfs` reads the repository's `hfs.json` and the slot manifest shipped in `runtime/`. The factory returns three
+`loadHfs` reads the repository's `hfs.json` and the slot manifest shipped in `runtime/`. The factory returns two
 flat-config blocks and owns everything about the law: which files are linted (from the HFS profile), which rules are on
 (every one, at `error` - nothing is off and nothing is a warning), the React Hooks rules (`eslint-plugin-react-hooks` 7, its
 recommended set lifted to `error`), typed linting, and the inline-directive fence (`noInlineConfig` plus
@@ -24,9 +24,8 @@ recommended set lifted to `error`), typed linting, and the inline-directive fenc
 - The **ignore** block: `node_modules`, `.next`, `dist`, `coverage`, `__generated__` and `.starci/`.
 - The **source** block governs `apps/*/src/**` and `packages/*/src/**` with types (`parserOptions.projectService`) and
   `settings.starci.hfs`, the slot view path-scoped rules ask (`lib/hfs.mjs` `hfsOf`), never a path pattern.
-- The **e2e** block governs `e2e/**` and `playwright.config.ts` with the e2e rules and the escape-hatch fence.
 
-`recommended`, `sourceRecommended`, `e2eRecommended`, `why`, `loadHfs`, `linterOptions` and the plugin itself are also
+`recommended`, `why`, `loadHfs`, `linterOptions` and the plugin itself are also
 exported; `why[rule]` is `{ code, vi, fixVi }`, the finding code and the Vietnamese why the harness quotes.
 
 ## Rules
@@ -36,8 +35,7 @@ its Vietnamese why. New in 5.0: [env-owner](docs/env-owner.md), [transport](docs
 [client-boundary](docs/client-boundary.md), [hooks-folder](docs/hooks-folder.md),
 [next-conventions](docs/next-conventions.md), [translation](docs/translation.md) (no literal copy at any
 tier, no `vn-ok`), [brand-values](docs/brand-values.md), [native-controls](docs/native-controls.md),
-[size-and-state-budget](docs/size-and-state-budget.md), [e2e-shape](docs/e2e-shape.md),
-[spec-quality](docs/spec-quality.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). New in 5.1: [lists](docs/lists.md), [hygiene](docs/hygiene.md), [formatting](docs/formatting.md) and [type-safety](docs/type-safety.md), plus rules added to next-conventions, client-boundary, native-controls and transport. New in 6.0: `effect-subscription-needs-cleanup` (timers, frames, listeners, observers, sockets and subscriptions are released against the same handle), `server-module-marks-server-only` ([client-boundary](docs/client-boundary.md)), `no-data-fetch-in-effect` sees indirect loads, `no-hardcoded-copy` reads templates and sentence values, `no-inline-lint-config` refuses `NOSONAR` and the coverage/formatter switches. Also new in 6.0: [grammar-boundary](docs/grammar-boundary.md) (`no-raw-structural-element`), `one-outcome-union` ([transport](docs/transport.md)), `i18n-stack-in-one-module` ([next-conventions](docs/next-conventions.md)), [size-growth](docs/size-growth.md) (`file-size-growth`: a file over the manifest's line budget is not born large and does not grow; the budget is `ruleParams.fe.fileLines`, read from the manifest copy in `runtime/`).
+[size-and-state-budget](docs/size-and-state-budget.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). New in 5.1: [lists](docs/lists.md), [hygiene](docs/hygiene.md), [formatting](docs/formatting.md) and [type-safety](docs/type-safety.md), plus rules added to next-conventions, client-boundary, native-controls and transport. New in 6.1: `no-vietnamese-in-source` (English-only identifiers, strings, comments and test titles; the i18n fixtures slot `e2e/fixtures/i18n/` is the one exemption). New in 6.0: `effect-subscription-needs-cleanup` (timers, frames, listeners, observers, sockets and subscriptions are released against the same handle), `server-module-marks-server-only` ([client-boundary](docs/client-boundary.md)), `no-data-fetch-in-effect` sees indirect loads, `no-hardcoded-copy` reads templates and sentence values, `no-inline-lint-config` refuses `NOSONAR` and the coverage/formatter switches. Also new in 6.0: [grammar-boundary](docs/grammar-boundary.md) (`no-raw-structural-element`), `one-outcome-union` ([transport](docs/transport.md)), `i18n-stack-in-one-module` ([next-conventions](docs/next-conventions.md)), [size-growth](docs/size-growth.md) (`file-size-growth`: a file over the manifest's line budget is not born large and does not grow; the budget is `ruleParams.fe.fileLines`, read from the manifest copy in `runtime/`).
 
 Older laws cover comments, file layout, icons and vendor ownership, landmarks, loading states,
 naming, props, served locales, component splits, design tokens, type safety, typography, and

package/client-boundary.mjs

@@ -16,11 +16,12 @@
  */
 
 import ts from "typescript"
-import { classifyImport, fileOf, isProductSource, isSpecFile, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
+import { classifyImport, fileOf, isProductSource, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
 import { typed } from "./lib/types.mjs"
 
 /** The route roles that are client-only by the framework's own rule: `error` and `global-error`. */
-const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error"])
+/** Route-tree roles that are client components by construction: the error boundaries, and the providers wrapper a layout renders. */
+const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error", "providers"])
 
 /** True when the program opens with the `"use client"` directive. */
 const clientDirective = (program) =>
@@ -58,13 +59,13 @@ export const useClientOnlyAtBoundary = {
     schema: [],
     messages: {
       slot:
-        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`.",
+        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`; context providers go in the route tree's `providers.tsx`.",
       elsewhere:
-        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, or on `error.tsx`/`global-error.tsx`. Below a client block the file is already client; above one it must stay a server component.",
+        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, on `error.tsx`/`global-error.tsx`, or on the route tree's `providers.tsx` (the context providers a layout renders around its children). Below a client block the file is already client; above one it must stay a server component.",
     },
   },
   create(context) {
-    if (isSpecFile(fileOf(context)) || isBoundary(context)) return {}
+    if (isBoundary(context)) return {}
     const slot = routeFill(context)
     return {
       Program(program) {
@@ -113,7 +114,6 @@ export const clientNoServerImport = {
     },
   },
   create(context) {
-    if (isSpecFile(fileOf(context))) return {}
     let client = false
     return {
       Program(program) {
@@ -171,7 +171,6 @@ export const serverModuleMarksServerOnly = {
     },
   },
   create(context) {
-    if (isSpecFile(fileOf(context))) return {}
     const slot = slotOfFile(context)
     if (!slot || ROUTE_FILE_SLOTS.has(slot)) return {}
     // A block or a page is a server or client COMPONENT, not a server module: whether client code reaches the server through it is
@@ -262,7 +261,6 @@ export const noDangerousHtml = {
     },
   },
   create(context) {
-    if (isSpecFile(context.filename || context.getFilename())) return {}
     return {
       JSXAttribute(node) {
         if (node.name.type !== "JSXIdentifier" || node.name.name !== "dangerouslySetInnerHTML") return

package/comments.mjs

@@ -5,21 +5,18 @@
  * would miss the one in a log message, so it walks comments, identifiers, string literals, template
  * chunks and JSX text alike - everywhere prose can hide in a source file.
  *
- * THE SECOND-LANGUAGE RULE IS GONE. It carried a `vn-ok: <reason>` pragma, an escape hatch that was
- * used 490 times in one repository, and one escape is enough to turn a rule into a comment
- * convention. Its job is now held by `no-hardcoded-copy` in `translation.mjs`, which has no
- * pragma: user-facing text comes from a `next-intl` catalogue, and the catalogue is the only place
- * a second language is content.
+ * `no-vietnamese-in-source` holds the English-only law: identifiers, string literals, template text, JSX text,
+ * comments and test titles carry no Vietnamese letter. The old `vn-ok: <reason>` pragma is gone (it was used 490
+ * times in one repository, and one escape is enough to turn a rule into a comment convention). Detection is
+ * structural on characters (`scripts/lib/language.mjs`, folded to NFC), never a word list.
  *
  * The exceptions that remain are placements, not judgements, and that is on purpose: a locale dictionary
  * IS the other language, and a fixture reproducing a real string has to reproduce it exactly. A
- * judgement-based exception would be argued per file forever.
+ * judgement-based exception would be argued per file forever. The Vietnamese rule has no placement exemption at all.
  */
 
-import { fileOf, inSlot, isSpecFile } from "./lib/scope.mjs"
-
-/** The letters that mark the second language a source string must not carry outside a catalogue. */
-export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/
+import { hasSecondLanguage } from "./runtime/scripts/lib/language.mjs"
+import { fileOf, inSlot } from "./lib/scope.mjs"
 
 /**
  * Extended pictographs, or a regional-indicator pair.
@@ -35,17 +32,16 @@ export const hasEmoji = (text) =>
 /**
  * Files whose second-language text or emoji is CONTENT rather than authoring, decided by what the file IS.
  *
- * Three kinds only: the locale dictionaries (a `.json` file of an i18n slot, `fe.modules.i18n` or `fe.package.i18n`),
- * which are the product's other language; the e2e support tree (slot `fe.e2e-support`: fixtures and support),
- * and specs, which reproduce real strings and would be testing something else if they translated them. There is no
- * "copy module": a `resources/` folder of strings is copy that skipped the catalogue.
+ * One kind only: the locale dictionaries (a `.json` file of an i18n slot, `fe.modules.i18n` or `fe.package.i18n`),
+ * which are the product's other language. There is no "copy module": a `resources/` folder of strings is copy that
+ * skipped the catalogue.
  *
  * @param {object} context - The ESLint rule context.
  * @returns {boolean} True when the linted file holds content rather than authoring.
  */
 export const isContentFile = (context) => {
   const file = fileOf(context)
-  return isSpecFile(file) || inSlot(context, "fe.e2e-support") || (inSlot(context, "fe.modules.i18n", "fe.package.i18n") && file.endsWith(".json"))
+  return inSlot(context, "fe.modules.i18n", "fe.package.i18n") && file.endsWith(".json")
 }
 
 /** Walk every place prose can hide, and hand each to one check. */
@@ -58,6 +54,12 @@ const proseVisitors = (context, report) => {
     Identifier(node) {
       report(node, node.name)
     },
+    JSXIdentifier(node) {
+      report(node, node.name)
+    },
+    PrivateIdentifier(node) {
+      report(node, node.name)
+    },
     Literal(node) {
       if (typeof node.value === "string") report(node, node.value)
     },
@@ -121,10 +123,31 @@ export const noEmojiInSource = {
   },
 }
 
+// -- COMMENTS-5 ------------------------------------------------------------------------------------
+
+/** Source prose is English: no Vietnamese letter in an identifier, string, comment, JSX text or test title. */
+export const noVietnameseInSource = {
+  meta: {
+    type: "problem",
+    docs: { description: "No Vietnamese in source authoring, specs included." },
+    schema: [],
+    messages: {
+      vietnamese:
+        "A Vietnamese letter in source. Every reader has to be able to read all of the code, its comments and its test titles, and half of a two-language file is unavailable to somebody. Write it in English; product copy lives in the `messages/<locale>.json` catalogue behind `t()`; there is no pragma.",
+    },
+  },
+  create(context) {
+    return proseVisitors(context, (node, text) => {
+      if (hasSecondLanguage(text)) context.report({ node, messageId: "vietnamese" })
+    })
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "require-export-jsdoc": requireExportJsdoc,
   "no-emoji-in-source": noEmojiInSource,
+  "no-vietnamese-in-source": noVietnameseInSource,
 }
 
 /**

package/docs/brand-values.md

@@ -25,6 +25,6 @@ const c = "#ff0000"
 
 **Finding code:** `FE_STYLE_TOKEN_ONLY`
 
-**Vì sao (why):** `<file>` dùng giá trị màu/độ dài thô (`<what>`). Màu và khoảng cách chỉ đến từ token grammar; màu thương hiệu chỉ ở `brand.css`.
+**Why:** `<file>` uses a raw colour/length value (`<what>`). Colours and spacing come only from grammar tokens; brand colours live only in `brand.css`.
 
-**Cách sửa:** Dùng lớp hoặc biến token của grammar; giá trị màu chỉ khai trong `modules/brand/brand.css`.
+**Fix:** Use a grammar token class or variable; colour values are declared only in `modules/brand/brand.css`.

package/docs/client-boundary.md

@@ -26,9 +26,9 @@ export const Feed = () => null
 
 **Finding code:** `FE_CLIENT_BOUNDARY`
 
-**Vì sao (why):** `"use client"` ở `<file>` (`<slot>` không được là client component).
+**Why:** `"use client"` in `<file>` (`<slot>` must not be a client component).
 
-**Cách sửa:** Đặt `"use client"` ở `index.tsx` của block có tương tác, leaf, hoặc `error.tsx`/`global-error.tsx`; giữ layout và page là server component.
+**Fix:** Put `"use client"` in the `index.tsx` of an interactive block, a leaf, or `error.tsx`/`global-error.tsx`; keep layouts and pages as server components.
 
 ## `starci-fe/client-no-server-import`
 
@@ -50,9 +50,9 @@ import useSWR from "swr"
 
 **Finding code:** `FE_CLIENT_SERVER_IMPORT`
 
-**Vì sao (why):** Client component ở `<file>` nhập mã chỉ tồn tại ở server (`server-only`, `next/headers`, module Node, server reader).
+**Why:** The client component at `<file>` imports code that exists only on the server (`server-only`, `next/headers`, Node modules, a server reader).
 
-**Cách sửa:** Đọc dữ liệu ở server component hoặc server reader rồi truyền xuống bằng props; hoặc dùng SWR gọi client của app.
+**Fix:** Read data in a server component or server reader and pass it down as props; or use SWR calling the app client.
 
 ## `starci-fe/server-module-marks-server-only`
 
@@ -75,9 +75,9 @@ export const readCourses = async () => (await headers()).get("x-locale")
 
 **Finding code:** `FE_SERVER_ONLY_MARK`
 
-**Vì sao (why):** Module `<file>` nhập API chỉ có ở server (`next/headers`, `next/server`, `next-intl/server`, module Node hoặc module đã là server-only) nhưng không mở đầu bằng `import "server-only"`.
+**Why:** Module `<file>` imports server-only APIs (`next/headers`, `next/server`, `next-intl/server`, Node modules or a module that is already server-only) but does not begin with `import "server-only"`.
 
-**Cách sửa:** Đặt `import "server-only"` làm câu lệnh đầu tiên của tệp; tệp route (`page`, `layout`, `route`, `proxy`) là server component sẵn nên không cần.
+**Fix:** Make `import "server-only"` the first statement of the file; route files (`page`, `layout`, `route`, `proxy`) are already server components so they do not need it.
 
 ## `starci-fe/web-storage-only-in-modules`
 
@@ -97,9 +97,9 @@ const draft = useTopUpDraft()
 
 **Finding code:** `FE_STORAGE_OUTSIDE_MODULES`
 
-**Vì sao (why):** `<file>` dùng `localStorage`/`sessionStorage` ngoài `modules/`; storage không có ở server và ném lỗi khi đầy hạn mức.
+**Why:** `<file>` uses `localStorage`/`sessionStorage` outside `modules/`; storage does not exist on the server and throws when the quota is full.
 
-**Cách sửa:** Đặt đọc/ghi sau một hook hoặc module trong `modules/` có bảo vệ (`typeof window`, try/catch) rồi gọi từ block.
+**Fix:** Put reads/writes behind a hook or a guarded module in `modules/` (`typeof window`, try/catch) and call it from a block.
 
 ## `starci-fe/no-dangerous-html`
 
@@ -119,6 +119,6 @@ const draft = useTopUpDraft()
 
 **Finding code:** `FE_DANGEROUS_HTML`
 
-**Vì sao (why):** `dangerouslySetInnerHTML` trên `<tag>` ở `<file>`: chuỗi bất kỳ trở thành HTML chạy được.
+**Why:** `dangerouslySetInnerHTML` on `<tag>` in `<file>`: an arbitrary string becomes executable HTML.
 
-**Cách sửa:** Render nội dung thành phần tử; chỉ `<script>` mang JSON-LD hoặc mã theme từ hằng số của app mới được dùng.
+**Fix:** Render content as elements; only a `<script>` carrying JSON-LD or theme code from an app constant may use it.

package/docs/env-owner.md

@@ -25,9 +25,9 @@ const url = config.apiUrl
 
 **Finding code:** `FE_ENV_OWNER`
 
-**Vì sao (why):** `<file>` đọc biến môi trường. Chỉ `modules/config` được đọc env.
+**Why:** `<file>` reads environment variables. Only `modules/config` may read env.
 
-**Cách sửa:** Đọc giá trị từ export có kiểu của `modules/config` thay vì `process.env`.
+**Fix:** Read the value from a typed export of `modules/config` instead of `process.env`.
 
 ## `starci-fe/no-hardcoded-endpoint-fallback`
 
@@ -47,6 +47,6 @@ const url = process.env.API_URL
 
 **Finding code:** `FE_ENV_OWNER`
 
-**Vì sao (why):** `<file>` có giá trị dự phòng cứng cho địa chỉ hoặc bí mật (`?? "http://localhost…"`). Thiếu biến ở production phải ném lỗi khi nạp cấu hình, không được lặng lẽ trỏ về máy dev.
+**Why:** `<file>` has a hard fallback value for an address or secret (`?? "http://localhost…"`). A missing variable in production must throw when the configuration loads, never silently point at a dev machine.
 
-**Cách sửa:** Xóa giá trị dự phòng; để `modules/config` ném lỗi khi thiếu biến ở production.
+**Fix:** Remove the fallback; let `modules/config` throw when a variable is missing in production.

package/docs/formatting.md

@@ -25,6 +25,6 @@ const format = useFormatter()
 
 **Finding code:** `FE_I18N_FORMATTER`
 
-**Vì sao (why):** `<file>` định dạng số, tiền hoặc ngày bằng `toLocale*String`, `new Intl.*`, `toFixed`, ký hiệu tiền dán vào template hoặc thư viện ngày, thay vì formatter của next-intl.
+**Why:** `<file>` formats a number, money or date with `toLocale*String`, `new Intl.*`, `toFixed`, a currency symbol pasted into a template, or a date library, instead of the next-intl formatter.
 
-**Cách sửa:** Dùng `useFormatter()` (hoặc `getFormatter()` ở server): `number(...)`, `dateTime(...)`, `relativeTime(...)`.
+**Fix:** Use `useFormatter()` (or `getFormatter()` on the server): `number(...)`, `dateTime(...)`, `relativeTime(...)`.

package/docs/grammar-boundary.md

@@ -28,6 +28,6 @@ export const Home = () => <SurfaceCard><Text>{t("intro")}</Text></SurfaceCard>
 
 **Finding code:** `FE_NATIVE_FORM_CONTROL`
 
-**Vì sao (why):** `<tag>` thô ở `<file>`. Cấu trúc trang và chữ được ghép từ component của grammar, không viết HTML thô.
+**Why:** Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not written as raw HTML.
 
-**Cách sửa:** Thay bằng component grammar tương ứng (`Heading`, `Text`, `SurfaceCard`, ...); nếu grammar chưa có, thêm vào grammar hoặc gói ui thay vì vẽ tại chỗ.
+**Fix:** Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if the grammar lacks one, add it to the grammar or the ui package instead of drawing it in place.

package/docs/hooks-folder.md

@@ -24,6 +24,6 @@ export const useCourse = () => 1
 
 **Finding code:** `FE_HOOKS_ARE_HOOKS`
 
-**Vì sao (why):** `<file>` trong `hooks/` không phải React hook. Reader server về `modules/api`, helper về `<domain>.shared.ts`.
+**Why:** `<file>` in `hooks/` is not a React hook. Server readers belong in `modules/api`, helpers in `<domain>.shared.ts`.
 
-**Cách sửa:** Mỗi tệp `use*.ts` một hook; helper dùng chung vào `<domain>.shared.ts`; reader server vào `modules/api/<domain>/read-*.ts`.
+**Fix:** One hook per `use*.ts` file; shared helpers go into `<domain>.shared.ts`; server readers go into `modules/api/<domain>/read-*.ts`.

package/docs/hygiene.md

@@ -51,9 +51,9 @@ const subscribe = (listener: () => void) => {
 
 **Finding code:** `FE_EFFECT_CLEANUP`
 
-**Vì sao (why):** `<timer>` ở `<file>` chạy ngoài effect hoặc trong effect không có cleanup gọi `clearTimeout`/`clearInterval`.
+**Why:** `<timer>` in `<file>` runs outside an effect, or inside an effect with no cleanup calling `clearTimeout`/`clearInterval`.
 
-**Cách sửa:** Đặt timer trong `useEffect` và trả `() => clearTimeout(id)`; hoặc chuyển vào một hook làm việc đó.
+**Fix:** Put the timer in `useEffect` and return `() => clearTimeout(id)`; or move it into a hook that does so.
 
 ## `starci-fe/no-data-fetch-in-effect`
 
@@ -73,9 +73,9 @@ const { data } = useSWR(key, fetcher)
 
 **Finding code:** `FE_EFFECT_FETCH`
 
-**Vì sao (why):** `useEffect` ở `<file>` tải dữ liệu (`await`, `fetch`, `.then`): không cache, không gộp request, không trạng thái loading/lỗi, không huỷ.
+**Why:** `useEffect` in `<file>` loads data (`await`, `fetch`, `.then`): no cache, no request merging, no loading/error state, no cancellation.
 
-**Cách sửa:** Đọc phía client bằng SWR gọi client của app (`hooks/`), phía route bằng server reader `modules/api/<domain>/read-*.ts`.
+**Fix:** Read on the client with SWR calling the app client (`hooks/`), and on the route side with a server reader `modules/api/<domain>/read-*.ts`.
 
 ## `starci-fe/no-empty-catch`
 
@@ -95,9 +95,9 @@ try { await save() } catch (error) { return { kind: "unavailable", cause: error
 
 **Finding code:** `FE_SWALLOWED_ERROR`
 
-**Vì sao (why):** `catch` hoặc `.catch` ở `<file>` không làm gì: lỗi biến mất, không thông báo, không dấu vết.
+**Why:** `catch` or `.catch` in `<file>` does nothing: the error vanishes, with no notice and no trace.
 
-**Cách sửa:** Trả một outcome có kiểu mang nguyên nhân, hiển thị trạng thái lỗi, hoặc ném lại.
+**Fix:** Return a typed outcome carrying the cause, show an error state, or rethrow.
 
 ## `starci-fe/no-console`
 
@@ -117,6 +117,6 @@ return { kind: "unavailable", cause: error }
 
 **Finding code:** `FE_CONSOLE_CALL`
 
-**Vì sao (why):** `console.<method>` ở `<file>`: không vào pipeline log nào và lộ chi tiết nội bộ cho người dùng.
+**Why:** `console.<method>` in `<file>`: it enters no log pipeline and exposes internal details to the user.
 
-**Cách sửa:** Trả outcome có kiểu, hiển thị trạng thái lỗi, hoặc để lỗi tới `error.tsx`.
+**Fix:** Return a typed outcome, show an error state, or let the error reach `error.tsx`.

package/docs/lint-escape-hatch.md

@@ -29,6 +29,6 @@ const s = 1
 
 **Finding code:** `HFS_INLINE_SUPPRESSION`
 
-**Vì sao (why):** Có chú thích tắt luật ở `<file>:<line>`. HFS không cho tắt tại chỗ — sửa code, hoặc đề xuất đổi luật.
+**Why:** There is a rule-disabling comment at `<file>:<line>`. HFS does not allow disabling in place - fix the code, or propose changing the rule.
 
-**Cách sửa:** Xóa `eslint-disable`, `@ts-ignore`, `@ts-expect-error` hoặc `vn-ok` và sửa nguyên nhân.
+**Fix:** Remove `eslint-disable`, `@ts-ignore`, `@ts-expect-error` or `vn-ok` and fix the cause.

package/docs/lists.md

@@ -24,9 +24,9 @@ rows.map((row) => <Row key={row.id} row={row} />)
 
 **Finding code:** `FE_LIST_KEY`
 
-**Vì sao (why):** Phần tử trả từ `.map` ở `<file>` không có `key`, nên React nhận diện hàng theo vị trí và hàng bị đổi state khi xoá hoặc sắp xếp lại.
+**Why:** An element returned from `.map` in `<file>` has no `key`, so React identifies rows by position and rows swap state when removed or reordered.
 
-**Cách sửa:** Thêm `key` lấy từ id của dữ liệu; với fragment dùng `<Fragment key={...}>`.
+**Fix:** Add a `key` taken from the data id; for a fragment use `<Fragment key={...}>`.
 
 ## `starci-fe/no-index-key`
 
@@ -46,9 +46,9 @@ rows.map((row) => <Row key={row.id} row={row} />)
 
 **Finding code:** `FE_LIST_KEY`
 
-**Vì sao (why):** `key` ở `<file>` lấy từ chỉ số của `.map` hoặc giá trị sinh ngẫu nhiên; chỉ số là vị trí, không phải danh tính.
+**Why:** The `key` in `<file>` comes from the `.map` index or a randomly generated value; an index is a position, not an identity.
 
-**Cách sửa:** Dùng id mà dữ liệu mang (`key={row.id}`); không dùng index, `Math.random`, `Date.now`.
+**Fix:** Use the id the data carries (`key={row.id}`); do not use index, `Math.random`, `Date.now`.
 
 ## `starci-fe/no-inline-literal-prop-in-list`
 
@@ -69,6 +69,6 @@ rows.map((row) => <Avatar key={row.id} props={AVATAR_PROPS} />)
 
 **Finding code:** `FE_LIST_KEY`
 
-**Vì sao (why):** Component trong `.map` ở `<file>` nhận object hoặc array literal làm prop: mỗi hàng mỗi lần render một giá trị mới, memo không bao giờ trúng.
+**Why:** A component inside `.map` in `<file>` receives an object or array literal as a prop: every row gets a new value on every render, so memo never hits.
 
-**Cách sửa:** Nâng hằng số ra ngoài component hoặc dựng một lần trước `.map`.
+**Fix:** Hoist the constant out of the component or build it once before `.map`.

package/docs/native-controls.md

@@ -24,9 +24,9 @@ Use the grammar's renderers; never a bare select, input, textarea or button.
 
 **Finding code:** `FE_NATIVE_FORM_CONTROL`
 
-**Vì sao (why):** `<tag>` thô ở `<file>`. Dùng renderer của grammar.
+**Why:** Raw `<tag>` in `<file>`. Use the grammar renderer.
 
-**Cách sửa:** Thay bằng thành phần của grammar; nếu chưa có, thêm vào grammar thay vì vẽ tại chỗ.
+**Fix:** Replace it with a grammar component; if none exists, add it to the grammar instead of drawing it in place.
 
 ## `starci-fe/no-native-img`
 
@@ -46,9 +46,9 @@ Use `next/image`, never a bare `<img>` (catalogue R62, sub-check `FE_NATIVE_IMAG
 
 **Finding code:** `FE_NATIVE_IMAGE`
 
-**Vì sao (why):** `<img>` thô ở `<file>`: tải ảnh gốc, không giữ chỗ nên trang nhảy khi ảnh tải xong.
+**Why:** Raw `<img>` in `<file>`: it loads the original image and reserves no space, so the page jumps when the image loads.
 
-**Cách sửa:** Dùng `Image` của `next/image` với `width` và `height` (hoặc `fill` và `sizes`) và `alt` từ catalog.
+**Fix:** Use `Image` from `next/image` with `width` and `height` (or `fill` and `sizes`) and `alt` from the catalog.
 
 ## `starci-fe/image-has-size`
 
@@ -68,6 +68,6 @@ Use `next/image`, never a bare `<img>` (catalogue R62, sub-check `FE_NATIVE_IMAG
 
 **Finding code:** `FE_NATIVE_IMAGE`
 
-**Vì sao (why):** `Image` ở `<file>` thiếu `width` và `height` (hoặc `fill` mà thiếu `sizes`): trình duyệt không giữ chỗ được.
+**Why:** `Image` in `<file>` lacks `width` and `height` (or has `fill` without `sizes`): the browser cannot reserve space.
 
-**Cách sửa:** Cho đủ `width` và `height`, hoặc `fill` trong khung có kích thước kèm `sizes`.
+**Fix:** Provide both `width` and `height`, or `fill` inside a sized frame together with `sizes`.

package/docs/next-conventions.md

@@ -24,9 +24,9 @@ export function proxy(request) { return request }
 
 **Finding code:** `FE_NEXT_CONVENTIONS`
 
-**Vì sao (why):** `<file>` dùng tên `middleware`. Từ Next 16 bộ chặn request là `proxy.ts` và xuất `proxy`.
+**Why:** `<file>` uses the name `middleware`. Since Next 16 the request interceptor is `proxy.ts` and exports `proxy`.
 
-**Cách sửa:** Đổi tên tệp thành `proxy.ts` và đổi export thành `proxy`.
+**Fix:** Rename the file to `proxy.ts` and rename the export to `proxy`.
 
 ## `starci-fe/locale-segment-is-locale`
 
@@ -46,9 +46,9 @@ export default function Page() {}
 
 **Finding code:** `FE_I18N_PLACEMENT`
 
-**Vì sao (why):** Tệp `<file>` nằm dưới segment ngôn ngữ không phải `[locale]`. Chỉ có một mẫu: `next-intl`, `[locale]`, mặc định `vi`.
+**Why:** The file `<file>` sits under a language segment that is not `[locale]`. There is only one pattern: `next-intl`, `[locale]`, default `vi`.
 
-**Cách sửa:** Đổi tên thư mục segment thành `[locale]`.
+**Fix:** Rename the segment directory to `[locale]`.
 
 ## `starci-fe/no-second-i18n-stack`
 
@@ -68,9 +68,9 @@ import { useTranslations } from "next-intl"
 
 **Finding code:** `FE_I18N_PLACEMENT`
 
-**Vì sao (why):** `<file>` nhập một thư viện i18n thứ hai. App chỉ dùng `next-intl` qua `modules/i18n`.
+**Why:** `<file>` imports a second i18n library. The app uses only `next-intl` through `modules/i18n`.
 
-**Cách sửa:** Chuyển sang `next-intl`; xóa thư viện còn lại.
+**Fix:** Switch to `next-intl`; remove the other library.
 
 ## `starci-fe/html-lang-from-locale`
 
@@ -90,9 +90,9 @@ import { useTranslations } from "next-intl"
 
 **Finding code:** `FE_I18N_LITERAL`
 
-**Vì sao (why):** `<html lang>` ở `<file>` là chữ cứng. Thuộc tính `lang` phải lấy từ segment `[locale]`.
+**Why:** `<html lang>` in `<file>` is hardcoded. The `lang` attribute must come from the `[locale]` segment.
 
-**Cách sửa:** Dùng `lang={locale}` từ tham số của layout `[locale]`.
+**Fix:** Use `lang={locale}` from the parameters of the `[locale]` layout.
 
 ## `starci-fe/page-exports-metadata`
 
@@ -113,9 +113,9 @@ export default function Page() { return <CoursesPage /> }
 
 **Finding code:** `FE_PAGE_METADATA_MISSING`
 
-**Vì sao (why):** `<file>` là `page.tsx` nhưng không export `metadata` hoặc `generateMetadata`; mọi trang trong nhánh mang cùng một tiêu đề.
+**Why:** `<file>` is a `page.tsx` but does not export `metadata` or `generateMetadata`; every page in the branch carries the same title.
 
-**Cách sửa:** Export `metadata` (hoặc `generateMetadata` khi tiêu đề lấy từ dữ liệu) với tiêu đề và mô tả lấy từ catalog thông điệp.
+**Fix:** Export `metadata` (or `generateMetadata` when the title comes from data) with the title and description taken from the message catalog.
 
 ## `starci-fe/no-null-suspense-fallback`
 
@@ -135,9 +135,9 @@ export default function Page() { return <CoursesPage /> }
 
 **Finding code:** `FE_SUSPENSE_NULL_FALLBACK`
 
-**Vì sao (why):** `<Suspense>` ở `<file>` có `fallback` rỗng: người dùng thấy khoảng trống thay vì trạng thái đang tải.
+**Why:** `<Suspense>` in `<file>` has an empty `fallback`: the user sees a blank space instead of a loading state.
 
-**Cách sửa:** Truyền skeleton (trạng thái loading) của đúng thứ đang tải làm `fallback`.
+**Fix:** Pass the skeleton (loading state) of exactly what is loading as the `fallback`.
 
 ## `starci-fe/navigation-from-intl`
 
@@ -157,9 +157,9 @@ import { useRouter } from "@/modules/i18n/navigation"
 
 **Finding code:** `FE_I18N_NAVIGATION`
 
-**Vì sao (why):** `<file>` nhập `Link`, `useRouter`, `usePathname` hoặc `redirect` từ Next, không biết locale: đường dẫn mất tiền tố `[locale]`.
+**Why:** `<file>` imports `Link`, `useRouter`, `usePathname` or `redirect` from Next, which is unaware of the locale: paths lose the `[locale]` prefix.
 
-**Cách sửa:** Nhập từ `modules/i18n/navigation`, được next-intl dựng từ `routing.ts`.
+**Fix:** Import from `modules/i18n/navigation`, which next-intl builds from `routing.ts`.
 
 ## `starci-fe/no-native-anchor`
 
@@ -179,9 +179,9 @@ An internal link is `Link` from `modules/i18n/navigation`; an external `_blank`
 
 **Finding code:** `FE_I18N_NAVIGATION`
 
-**Vì sao (why):** `<a>` ở `<file>` trỏ route nội bộ (tải lại cả trang, mất locale, mất prefetch) hoặc mở tab mới mà không có `rel`.
+**Why:** `<a>` in `<file>` points at an internal route (reloads the whole page, loses the locale, loses prefetch) or opens a new tab without `rel`.
 
-**Cách sửa:** Dùng `Link` từ `modules/i18n/navigation` với href dựng bởi `modules/routes`; liên kết `_blank` thêm `rel="noopener noreferrer"`.
+**Fix:** Use `Link` from `modules/i18n/navigation` with an href built by `modules/routes`; for `_blank` links add `rel="noopener noreferrer"`.
 
 ## `starci-fe/no-hardcoded-route`
 
@@ -201,9 +201,9 @@ router.push(routes.newWorkspace())
 
 **Finding code:** `FE_ROUTE_HARDCODED`
 
-**Vì sao (why):** `<file>` viết thẳng đường dẫn route ở nơi gọi; route đổi chỗ thì bản sao trỏ vào 404.
+**Why:** `<file>` writes a route path directly at the call site; when the route moves, the copy points at a 404.
 
-**Cách sửa:** Dựng href bằng hàm của `modules/routes` và dùng đúng hàm đó ở mọi nơi.
+**Fix:** Build the href with a function from `modules/routes` and use that same function everywhere.
 
 ## `starci-fe/i18n-stack-in-one-module`
 
@@ -227,6 +227,6 @@ export const i18n = createAppI18n({ locales: ["vi"] })
 
 **Finding code:** `FE_I18N_PLACEMENT`
 
-**Vì sao (why):** `<file>` tự dựng một tầng của stack next-intl (`defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware`). Stack chỉ được viết một lần cho cả repo.
+**Why:** `<file>` builds a layer of the next-intl stack itself (`defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware`). The stack may be written only once per repo.
 
-**Cách sửa:** Gọi factory `createAppI18n` của gói i18n dùng chung trong `modules/i18n/index.ts` và nhập kết quả; repo một app thì chỉ viết stack trong `modules/i18n` của app đó.
+**Fix:** Call the `createAppI18n` factory of the shared i18n package in `modules/i18n/index.ts` and import the result; in a single-app repo, write the stack only in that app's `modules/i18n`.