@starci/eslint-canon-fe 3.0.2 → 5.1.2

package/lib/why.mjs

@@ -0,0 +1,304 @@
+/**
+ * The Vietnamese "why" of each rule the HFS catalogue assigns to this canon.
+ *
+ * WHERE IT IS SURFACED. An ESLint message is written for the developer at the terminal, in English,
+ * and says what is wrong in the vocabulary of the rule. The agent that reads a failed land gate needs
+ * the catalogue's sentence instead: the finding code (the key in `modules/kernel/failure-codes.yaml`)
+ * and a Vietnamese headline and next step it can quote to the owner. This map is the canon's half of
+ * that contract: `code` is the finding code, `vi` the headline with `<file>` / `<what>` placeholders
+ * the reader fills from the ESLint location, `fixVi` the one sentence "what do I do now".
+ *
+ * Every rule that carries a catalogue id (R18, R22, R49-R59, R60-R62, R65-R67) has an entry;
+ * the twin test refuses a rule of those laws with no entry and an entry for a rule that does not exist.
+ */
+
+/** @typedef {{ code: string, vi: string, fixVi: string }} Why */
+
+/** @type {Record<string, Why>} */
+export const why = {
+  "no-env-outside-config": {
+    code: "FE_ENV_OWNER",
+    vi: "`<file>` đọc biến môi trường. Chỉ `modules/config` được đọc env.",
+    fixVi: "Đọc giá trị từ export có kiểu của `modules/config` thay vì `process.env`.",
+  },
+  "no-hardcoded-endpoint-fallback": {
+    code: "FE_ENV_OWNER",
+    vi: "`<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.",
+    fixVi: "Xóa giá trị dự phòng; để `modules/config` ném lỗi khi thiếu biến ở production.",
+  },
+  "fetch-only-in-api-client": {
+    code: "FE_TRANSPORT_OWNER",
+    vi: "`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.",
+    fixVi: "Gọi client của app và nhận `Outcome<T>`; không tự gọi `fetch`.",
+  },
+  "client-fetch-has-signal": {
+    code: "FE_TRANSPORT_OWNER",
+    vi: "`fetch` ở `<file>` không có `signal`. Client bắt buộc có timeout và `AbortSignal`.",
+    fixVi: "Truyền `signal` (`AbortSignal.timeout(...)` kết hợp với tín hiệu của người gọi).",
+  },
+  "no-shared-transport-state": {
+    code: "FE_TRANSPORT_OWNER",
+    vi: "`<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.",
+    fixVi: "Truyền credential và locale bằng tham số hoặc context.",
+  },
+  "client-maps-auth-to-refused": {
+    code: "FE_HTTP_STATUS_COLLAPSE",
+    vi: "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.",
+    fixVi: "Thêm nhánh 401/403 trả `{ kind: \"refused\" }` trong client.",
+  },
+  "no-http-status-collapse": {
+    code: "FE_HTTP_STATUS_COLLAPSE",
+    vi: "`<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`.",
+    fixVi: "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.",
+  },
+  "no-hand-typed-wire": {
+    code: "FE_WIRE_GENERATED",
+    vi: "`<file>` tự gõ kiểu wire hoặc ép kiểu phản hồi. Dùng kiểu sinh từ `contract/`.",
+    fixVi: "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`.",
+  },
+  "use-client-only-at-boundary": {
+    code: "FE_CLIENT_BOUNDARY",
+    vi: "`\"use client\"` ở `<file>` (`<slot>` không được là client component).",
+    fixVi: "Đặ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.",
+  },
+  "hooks-folder-holds-hooks-only": {
+    code: "FE_HOOKS_ARE_HOOKS",
+    vi: "`<file>` trong `hooks/` không phải React hook. Reader server về `modules/api`, helper về `<domain>.shared.ts`.",
+    fixVi: "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`.",
+  },
+  "no-middleware-file": {
+    code: "FE_NEXT_CONVENTIONS",
+    vi: "`<file>` dùng tên `middleware`. Từ Next 16 bộ chặn request là `proxy.ts` và xuất `proxy`.",
+    fixVi: "Đổi tên tệp thành `proxy.ts` và đổi export thành `proxy`.",
+  },
+  "locale-segment-is-locale": {
+    code: "FE_I18N_PLACEMENT",
+    vi: "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`.",
+    fixVi: "Đổi tên thư mục segment thành `[locale]`.",
+  },
+  "no-second-i18n-stack": {
+    code: "FE_I18N_PLACEMENT",
+    vi: "`<file>` nhập một thư viện i18n thứ hai. App chỉ dùng `next-intl` qua `modules/i18n`.",
+    fixVi: "Chuyển sang `next-intl`; xóa thư viện còn lại.",
+  },
+  "html-lang-from-locale": {
+    code: "FE_I18N_LITERAL",
+    vi: "`<html lang>` ở `<file>` là chữ cứng. Thuộc tính `lang` phải lấy từ segment `[locale]`.",
+    fixVi: "Dùng `lang={locale}` từ tham số của layout `[locale]`.",
+  },
+  "no-hardcoded-copy": {
+    code: "FE_I18N_LITERAL",
+    vi: "Chữ `\"<text>\"` ở `<file>:<line>` không đi qua `t()`.",
+    fixVi: "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`.",
+  },
+  "no-raw-brand-value": {
+    code: "FE_STYLE_TOKEN_ONLY",
+    vi: "`<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`.",
+    fixVi: "Dùng lớp hoặc biến token của grammar; giá trị màu chỉ khai trong `modules/brand/brand.css`.",
+  },
+  "no-native-form-control": {
+    code: "FE_NATIVE_FORM_CONTROL",
+    vi: "`<tag>` thô ở `<file>`. Dùng renderer của grammar.",
+    fixVi: "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ỗ.",
+  },
+  "component-line-budget": {
+    code: "FE_SIZE_AND_STATE_BUDGET",
+    vi: "`<file>` dài `<n>` dòng, vượt ngưỡng 300 dòng của một component.",
+    fixVi: "Tách phần vẽ khỏi phần dữ liệu và tách từng khu vực thành đơn vị riêng.",
+  },
+  "unit-hook-budget": {
+    code: "FE_SIZE_AND_STATE_BUDGET",
+    vi: "`<unit>` có `<n>` hook dữ liệu / `<m>` useState, vượt ngưỡng 6.",
+    fixVi: "Gom trạng thái đổi cùng nhau vào reducer hoặc hook riêng; tách mỗi vùng dữ liệu thành block kết nối riêng.",
+  },
+  "no-hand-rolled-polling": {
+    code: "FE_SIZE_AND_STATE_BUDGET",
+    vi: "`<unit>` tự viết vòng poll (`setInterval` hoặc `setTimeout` tự gọi lại).",
+    fixVi: "Làm tươi qua hook dữ liệu (`refreshInterval`) hoặc socket, mỗi resource đúng một cơ chế.",
+  },
+  "e2e-spec-location": {
+    code: "FE_E2E_SHAPE",
+    vi: "Spec e2e `<file>` không nằm ở `e2e/<area>/<name>.e2e-spec.ts`.",
+    fixVi: "Đưa spec vào `e2e/<area>/` với hậu tố `.e2e-spec.ts`; helper vào `e2e/support/` hoặc `e2e/fixtures/`.",
+  },
+  "e2e-no-absolute-path": {
+    code: "FE_E2E_SHAPE",
+    vi: "Spec e2e `<file>` dùng đường dẫn tuyệt đối.",
+    fixVi: "Dựng đường dẫn từ cấu hình hoặc thư mục của chính spec.",
+  },
+  "e2e-no-docker": {
+    code: "FE_E2E_SHAPE",
+    vi: "Spec e2e `<file>` phụ thuộc vào docker.",
+    fixVi: "Trỏ suite tới một URL từ cấu hình; môi trường tự cung cấp stack.",
+  },
+  "e2e-no-cross-repo-write": {
+    code: "FE_E2E_SHAPE",
+    vi: "Spec e2e `<file>` ghi ra ngoài repo của app (đường dẫn tuyệt đối hoặc `..`).",
+    fixVi: "Chỉ ghi vào thư mục kết quả của chính repo này.",
+  },
+  "e2e-no-skip": {
+    code: "FE_E2E_SHAPE",
+    vi: "Spec e2e `<file>` bỏ qua test (`test.skip`/`fixme`) — thiếu môi trường phải làm suite đỏ, không được xanh.",
+    fixVi: "Sửa môi trường hoặc xóa test; không bỏ qua có điều kiện.",
+  },
+  "e2e-typed-helpers": {
+    code: "FE_E2E_SHAPE",
+    vi: "Helper e2e ở `<file>` có tham số không kiểu hoặc dùng `any`.",
+    fixVi: "Khai kiểu cho mọi tham số của helper; thay `any` bằng kiểu thật hoặc `unknown` kèm kiểm tra.",
+  },
+  "playwright-viewports": {
+    code: "FE_E2E_SHAPE",
+    vi: "`playwright.config` không khai đúng ba viewport 1440x900, 768x1024, 390x844.",
+    fixVi: "Mỗi project khai một viewport; đủ ba, không thêm cỡ thứ tư.",
+  },
+  "no-class-string-in-spec": {
+    code: "FE_SPEC_QUALITY",
+    vi: "Spec `<file>` ghim chuỗi class. Spec kiểm hành vi, không kiểm stylesheet.",
+    fixVi: "Assert theo role, tên, trạng thái hoặc chữ hiển thị.",
+  },
+  "spec-tests-its-neighbour": {
+    code: "FE_SPEC_QUALITY",
+    vi: "Spec `<file>` không import chủ thể nằm cạnh nó.",
+    fixVi: "Đưa spec về cạnh chủ thể, hoặc test đúng đơn vị nằm cạnh.",
+  },
+  "no-barrel-spec": {
+    code: "FE_SPEC_QUALITY",
+    vi: "Spec `<file>` đặt cạnh một barrel. Barrel không có hành vi để test.",
+    fixVi: "Xóa spec; test từng đơn vị mà barrel xuất lại, cạnh chính đơn vị đó.",
+  },
+  "no-double-cast-in-spec": {
+    code: "FE_SPEC_QUALITY",
+    vi: "Spec `<file>` ép kiểu hai lần (`as unknown as`).",
+    fixVi: "Dựng giá trị bằng factory có kiểu (`mock<T>()` hoặc fixture builder).",
+  },
+  "connected-spec-has-axe": {
+    code: "FE_SPEC_QUALITY",
+    vi: "Spec `<file>` của màn hình kết nối không có assert axe.",
+    fixVi: "Thêm `expect(await axe(container)).toHaveNoViolations()`.",
+  },
+  "no-mocked-translations": {
+    code: "FE_I18N_CATALOG",
+    vi: "Spec `<file>` giả lập `next-intl`, nên chỉ kiểm khóa chứ không kiểm catalog thật.",
+    fixVi: "Render trong `NextIntlClientProvider` với `messages/<locale>.json` thật.",
+  },
+  "no-inline-lint-config": {
+    code: "HFS_INLINE_SUPPRESSION",
+    vi: "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.",
+    fixVi: "Xóa `eslint-disable`, `@ts-ignore`, `@ts-expect-error` hoặc `vn-ok` và sửa nguyên nhân.",
+  },
+  "no-double-cast": {
+    code: "FE_TYPE_ESCAPE",
+    vi: "`<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.",
+    fixVi: "Thu hẹp từ `unknown` bằng type guard hoặc parser; không ép kiểu.",
+  },
+  "no-type-assertion": {
+    code: "FE_TYPE_ESCAPE",
+    vi: "`<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.",
+    fixVi: "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.",
+  },
+  "no-non-null-assertion": {
+    code: "FE_TYPE_ESCAPE",
+    vi: "`<file>` dùng `x!`: khẳng định giá trị có mặt mà không chứng minh.",
+    fixVi: "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.",
+  },
+  "no-explicit-any": {
+    code: "FE_TYPE_ESCAPE",
+    vi: "`<file>` dùng `any`: tắt kiểm kiểu cho giá trị đó và mọi thứ suy ra từ nó.",
+    fixVi: "Dùng kiểu thật, generic, hoặc `unknown` rồi thu hẹp tại chỗ dùng.",
+  },
+  "list-item-has-key": {
+    code: "FE_LIST_KEY",
+    vi: "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.",
+    fixVi: "Thêm `key` lấy từ id của dữ liệu; với fragment dùng `<Fragment key={...}>`.",
+  },
+  "no-index-key": {
+    code: "FE_LIST_KEY",
+    vi: "`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.",
+    fixVi: "Dùng id mà dữ liệu mang (`key={row.id}`); không dùng index, `Math.random`, `Date.now`.",
+  },
+  "no-inline-literal-prop-in-list": {
+    code: "FE_LIST_KEY",
+    vi: "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.",
+    fixVi: "Nâng hằng số ra ngoài component hoặc dựng một lần trước `.map`.",
+  },
+  "timer-needs-effect-cleanup": {
+    code: "FE_EFFECT_CLEANUP",
+    vi: "`<timer>` ở `<file>` chạy ngoài effect hoặc trong effect không có cleanup gọi `clearTimeout`/`clearInterval`.",
+    fixVi: "Đặt timer trong `useEffect` và trả `() => clearTimeout(id)`; hoặc chuyển vào một hook làm việc đó.",
+  },
+  "no-data-fetch-in-effect": {
+    code: "FE_EFFECT_FETCH",
+    vi: "`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ỷ.",
+    fixVi: "Đọ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`.",
+  },
+  "no-empty-catch": {
+    code: "FE_SWALLOWED_ERROR",
+    vi: "`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.",
+    fixVi: "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.",
+  },
+  "no-console": {
+    code: "FE_CONSOLE_CALL",
+    vi: "`console.<method>` ở `<file>`: không vào pipeline log nào và lộ chi tiết nội bộ cho người dùng.",
+    fixVi: "Trả outcome có kiểu, hiển thị trạng thái lỗi, hoặc để lỗi tới `error.tsx`.",
+  },
+  "page-exports-metadata": {
+    code: "FE_PAGE_METADATA_MISSING",
+    vi: "`<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 đề.",
+    fixVi: "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.",
+  },
+  "no-null-suspense-fallback": {
+    code: "FE_SUSPENSE_NULL_FALLBACK",
+    vi: "`<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.",
+    fixVi: "Truyền skeleton (trạng thái loading) của đúng thứ đang tải làm `fallback`.",
+  },
+  "navigation-from-intl": {
+    code: "FE_I18N_NAVIGATION",
+    vi: "`<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]`.",
+    fixVi: "Nhập từ `modules/i18n/navigation`, được next-intl dựng từ `routing.ts`.",
+  },
+  "no-native-anchor": {
+    code: "FE_I18N_NAVIGATION",
+    vi: "`<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`.",
+    fixVi: "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\"`.",
+  },
+  "use-intl-formatter": {
+    code: "FE_I18N_FORMATTER",
+    vi: "`<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.",
+    fixVi: "Dùng `useFormatter()` (hoặc `getFormatter()` ở server): `number(...)`, `dateTime(...)`, `relativeTime(...)`.",
+  },
+  "no-hardcoded-route": {
+    code: "FE_ROUTE_HARDCODED",
+    vi: "`<file>` viết thẳng đường dẫn route ở nơi gọi; route đổi chỗ thì bản sao trỏ vào 404.",
+    fixVi: "Dựng href bằng hàm của `modules/routes` và dùng đúng hàm đó ở mọi nơi.",
+  },
+  "client-no-server-import": {
+    code: "FE_CLIENT_SERVER_IMPORT",
+    vi: "Client component ở `<file>` nhập mã chỉ tồn tại ở server (`server-only`, `next/headers`, module Node, server reader).",
+    fixVi: "Đọ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.",
+  },
+  "web-storage-only-in-modules": {
+    code: "FE_STORAGE_OUTSIDE_MODULES",
+    vi: "`<file>` dùng `localStorage`/`sessionStorage` ngoài `modules/`; storage không có ở server và ném lỗi khi đầy hạn mức.",
+    fixVi: "Đặ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.",
+  },
+  "no-dangerous-html": {
+    code: "FE_DANGEROUS_HTML",
+    vi: "`dangerouslySetInnerHTML` trên `<tag>` ở `<file>`: chuỗi bất kỳ trở thành HTML chạy được.",
+    fixVi: "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.",
+  },
+  "no-native-img": {
+    code: "FE_NATIVE_IMAGE",
+    vi: "`<img>` thô ở `<file>`: tải ảnh gốc, không giữ chỗ nên trang nhảy khi ảnh tải xong.",
+    fixVi: "Dùng `Image` của `next/image` với `width` và `height` (hoặc `fill` và `sizes`) và `alt` từ catalog.",
+  },
+  "image-has-size": {
+    code: "FE_NATIVE_IMAGE",
+    vi: "`Image` ở `<file>` thiếu `width` và `height` (hoặc `fill` mà thiếu `sizes`): trình duyệt không giữ chỗ được.",
+    fixVi: "Cho đủ `width` và `height`, hoặc `fill` trong khung có kích thước kèm `sizes`.",
+  },
+  "outcome-kinds-exhaustive": {
+    code: "FE_OUTCOME_KIND_UNHANDLED",
+    vi: "`switch` trên `kind` ở `<file>` có nhánh `ok` nhưng thiếu một trong refused, invalid, not-found, unavailable.",
+    fixVi: "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/lint-adoption.mjs

@@ -3,10 +3,11 @@
  *
  * An ESLint config can import a plugin, copy a plugin, or call itself StarCi while still leaving
  * canonical rules switched off. The only useful evidence is the effective config ESLint applies
- * to a real production file. This audit compares that printed config with this canon.
+ * to a real production file. This audit compares that printed config with this canon: pass `sourceRecommended`
+ * for a production probe file and `e2eRecommended` for an e2e probe, since each tree has its own rules.
  */
 /**
- * Where the component tree sits, per supported repository shape.
+ * Where each tree sits, per supported repository shape.
  *
  * ONE BRANCH, IN ONE PLACE. The difference between a monorepo and a single app is not a difference
  * of law - the rules, their severities and the inline-config refusal are identical. It is only
@@ -14,65 +15,27 @@
  * lists, and the lists did what hand-kept lists do: one enabled 43 rules, the other 53, and canon
  * had 49. Neither repository was wrong on purpose; nothing told either of them.
  *
+ * TWO TREES. `src` is the product source, governed by every law except the e2e one; `e2e` is the
+ * Playwright tree and its config, governed by the e2e law and the escape-hatch fence.
+ *
  * The candidate path is included deliberately. A Preview candidate is the exact source Apply later
  * ports into production, and leaving it ungoverned means the one file that becomes production was
  * judged by nothing.
  */
-const LAYOUT_GLOBS = {
-    monorepo: [
-        "packages/ui/src/**/*.{ts,tsx}",
-        "apps/*/src/**/*.{ts,tsx}",
-        "**/candidate/src/**/*.{ts,tsx}",
-    ],
-    "single-app": [
-        "src/**/*.{ts,tsx}",
-        "**/candidate/src/**/*.{ts,tsx}",
-    ],
+export const LAYOUT_GLOBS = {
+    monorepo: {
+        src: ["packages/*/src/**/*.{ts,tsx}", "apps/*/src/**/*.{ts,tsx}", "**/candidate/src/**/*.{ts,tsx}"],
+        e2e: ["e2e/**/*.{ts,tsx}", "apps/*/e2e/**/*.{ts,tsx}", "packages/*/e2e/**/*.{ts,tsx}", "playwright.config.{ts,mts}", "apps/*/playwright.config.{ts,mts}"],
+    },
+    "single-app": {
+        src: ["src/**/*.{ts,tsx}", "**/candidate/src/**/*.{ts,tsx}"],
+        e2e: ["e2e/**/*.{ts,tsx}", "playwright.config.{ts,mts}"],
+    },
 }
 
 /** The repository shapes this canon knows how to govern. */
 export const LAYOUTS = Object.keys(LAYOUT_GLOBS)
 
-/**
- * The one flat-config block that attaches this canon to a repository.
- *
- * A consuming `eslint.config.mjs` spreads the result and owns nothing else about the rules: not
- * which are on, not their severity, not whether an inline comment may switch one off. Its own
- * plugins, its own ignores and its own language options stay its own business - what it may not
- * keep is a second opinion about the law.
- *
- * @param {object} input - Attachment options.
- * @param {"monorepo" | "single-app"} input.layout - Which shape this repository has.
- * @param {object} input.plugin - The plugin object, imported from this canon.
- * @param {object} input.recommended - The recommendation, imported from this canon.
- * @param {object} input.linterOptions - The linter options, imported from this canon.
- * @returns {object} One flat-config block.
- */
-export const starciFeConfig = ({ layout, plugin, recommended, linterOptions }) => {
-    const files = LAYOUT_GLOBS[layout]
-    if (!files) {
-        throw new Error(`unknown layout "${layout}" - expected one of: ${LAYOUTS.join(", ")}`)
-    }
-    /*
-     * `recommended` is a FLAT rule map here, not a config object with a `rules` key - and reaching
-     * for `.rules` on it is the mistake this line exists to stop repeating. Spread that way it
-     * yields `undefined`, the block ends up with zero rules, and the repository lints clean while
-     * being governed by nothing. That is the worst possible failure for this file: green, silent,
-     * and indistinguishable from success. Both spellings are accepted so neither shape can produce
-     * an empty block.
-     */
-    const rules = recommended?.rules ?? recommended
-    if (!rules || Object.keys(rules).length === 0) {
-        throw new Error("starciFeConfig received an empty recommendation - a config with no rules is not adoption")
-    }
-    return {
-        files,
-        linterOptions,
-        plugins: { "starci-fe": plugin },
-        rules: { ...rules },
-    }
-}
-
 /** Convert every flat-config severity spelling to its numeric meaning. */
 const severityOf = (setting) => {
   const severity = Array.isArray(setting) ? setting[0] : setting

package/lint-escape-hatch.mjs

@@ -1,56 +1,91 @@
-/** The rule and flat-config fence that hold `lint-escape-hatch.md`. */
-
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** Product source is governed; canon tests deliberately construct forbidden directives. */
-const isProductSource = (filename) => normalizePath(filename).includes("/src/")
-
-/**
- * Any directive that changes ESLint's active rule set inside a source file.
- *
- * ANCHORED AT THE START OF THE COMMENT, because that is the only place ESLint itself honours one:
- * a directive is recognised from the first non-space character of the comment body and nowhere else.
- * An unanchored pattern matched the WORD instead of the directive, so a comment explaining why a
- * file carries no `eslint-disable` was reported as carrying one - and the only way to silence that
- * was to stop writing the explanation, which is the opposite of what this law wants. Under-catching
- * is not the trade: a directive ESLint would obey always sits at the start.
- */
-const INLINE_DIRECTIVE = /^\s*eslint-(?:disable(?:-next-line|-line)?|enable)\b/
-
-/** Inline lint configuration is repository policy, never a file-local choice. */
-export const noInlineLintConfig = {
-  meta: {
-    type: "problem",
-    docs: { description: "Product source cannot change its own ESLint policy." },
-    schema: [],
-    messages: {
-      directive:
-        "Inline ESLint configuration makes this file the author of whether repository law applies. Remove the directive and fix the code or the shared rule; there is no local exception path.",
-    },
-  },
-  create(context) {
-    if (!isProductSource(context.filename || context.getFilename())) return {}
-    const source = context.sourceCode || context.getSourceCode()
-    return {
-      Program() {
-        for (const comment of source.getAllComments()) {
-          if (INLINE_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "directive" })
-        }
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-inline-lint-config": noInlineLintConfig,
-}
-
-/** Every lint escape is a build error. */
-export const recommended = {
-  "starci-fe/no-inline-lint-config": "error",
-}
-
-/** Consuming flat configs apply this beside the recommended rules. */
-export const linterOptions = Object.freeze({ noInlineConfig: true })
+/**
+ * The rule and flat-config fence that hold `lint-escape-hatch.md` (HFS R18, `HFS_INLINE_SUPPRESSION`).
+ *
+ * NO LOCAL EXCEPTION, OF ANY SPELLING. A rule that a comment can switch off is a convention, and a
+ * codebase learns which conventions are real by which ones it can suppress. The spellings this law
+ * refuses are the ones an author actually reaches for:
+ *
+ *   eslint-disable / -next-line / -line / -enable / -env, and `/* eslint rule: "off" *\/`
+ *   @ts-ignore, @ts-expect-error, @ts-nocheck
+ *   vn-ok: <reason>   - the retired second-language pragma; it excuses nothing any more
+ *
+ * TWO LAYERS, BECAUSE ONE IS NOT ENOUGH. The flat-config fence (`noInlineConfig`) makes an ESLint
+ * directive INEFFECTIVE; this rule makes it a FINDING, so the attempt is named in the log instead of
+ * silently ignored. `reportUnusedDisableDirectives` closes the last gap: a directive that suppresses
+ * nothing is dead weight that reads as if it did.
+ */
+
+import { isE2eFile, isProductFile, isSpecFile } from "./lib/scope.mjs"
+import { normalizePath } from "./lib/path.mjs"
+
+/** Product source, its specs and the e2e tree are governed; canon tests deliberately build forbidden directives. */
+const isGoverned = (filename) => {
+  const file = normalizePath(filename)
+  return isProductFile(file) || isSpecFile(file) || isE2eFile(file)
+}
+
+/**
+ * Any directive that changes ESLint's active rule set inside a source file.
+ *
+ * ANCHORED AT THE START OF THE COMMENT, because that is the only place ESLint itself honours one:
+ * a directive is recognised from the first non-space character of the comment body and nowhere else.
+ * An unanchored pattern matched the WORD instead of the directive, so a comment explaining why a
+ * file carries no `eslint-disable` was reported as carrying one - and the only way to silence that
+ * was to stop writing the explanation, which is the opposite of what this law wants. Under-catching
+ * is not the trade: a directive ESLint would obey always sits at the start.
+ */
+const ESLINT_DIRECTIVE = /^\s*eslint-(?:disable(?:-next-line|-line)?|enable|env)\b|^\s*eslint\s+[@\w/-]+\s*:/
+
+/** A TypeScript directive that turns the compiler's check off for the next line or the file. */
+const TS_DIRECTIVE = /^\s*(?:\/\s*)?@ts-(?:ignore|expect-error|nocheck)\b/
+
+/** The retired second-language pragma. Present anywhere in a comment, it is a finding. */
+const RETIRED_PRAGMA = /\bvn-ok:/
+
+/** Inline lint configuration is repository policy, never a file-local choice. */
+export const noInlineLintConfig = {
+  meta: {
+    type: "problem",
+    docs: { description: "Source cannot change its own lint or type-check policy, and the vn-ok pragma is retired." },
+    schema: [],
+    messages: {
+      directive:
+        "Inline ESLint configuration makes this file the author of whether repository law applies. Remove the directive and fix the code or the shared rule; there is no local exception path.",
+      typescript:
+        "A TypeScript suppression directive. It turns the compiler off for code that is failing the check for a reason. Fix the type, or change the shared contract that produced it; there is no local exception path.",
+      pragma:
+        "`vn-ok:` was the second-language escape hatch and it is retired: user-facing text comes from a `next-intl` catalogue through `t()`, and there is no comment that excuses a literal. Remove the pragma and move the string.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    return {
+      Program() {
+        for (const comment of source.getAllComments()) {
+          if (ESLINT_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "directive" })
+          else if (TS_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "typescript" })
+          else if (RETIRED_PRAGMA.test(comment.value)) context.report({ node: comment, messageId: "pragma" })
+        }
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-inline-lint-config": noInlineLintConfig,
+}
+
+/** Every lint escape is a build error. */
+export const recommended = {
+  "starci-fe/no-inline-lint-config": "error",
+}
+
+/**
+ * Consuming flat configs apply this beside the recommended rules.
+ *
+ * `noInlineConfig` makes an inline directive ineffective; `reportUnusedDisableDirectives` makes one
+ * that suppresses nothing an error, so a leftover from before the fence is not mistaken for a live one.
+ */
+export const linterOptions = Object.freeze({ noInlineConfig: true, reportUnusedDisableDirectives: "error" })