@starci/eslint-canon-fe 5.1.2 → 6.0.0

package/docs/hygiene.md

@@ -2,13 +2,24 @@
 
 Law module: `hygiene.mjs`. Catalogue: R65 FE_SIZE_AND_STATE_BUDGET (sub-checks `FE_EFFECT_CLEANUP`, `FE_SWALLOWED_ERROR`, `FE_CONSOLE_CALL`) and R50 FE_TRANSPORT_OWNER (sub-check `FE_EFFECT_FETCH`).
 
-Work started by a component that nobody owns the end of: a timer that outlives the component, a fetch in an effect with no cache or cancel, an empty `catch` that hides the failure, a `console` call no pipeline reads. `modules/**` is exempt from the timer rule only (the API client owns its timeout timer and clears it in `finally`).
+Work started by a component that nobody owns the end of: a timer, listener, observer, socket or subscription that outlives the component, a fetch in an effect with no cache or cancel, an empty `catch` that hides the failure, a `console` call no pipeline reads. Every rule here decides by resolution: an effect is a call to React's own `useEffect` / `useLayoutEffect` export (the import is followed), the timer or listener is the platform's when its symbol is declared by the default library, "the same handle" is the same scope binding (or member path such as `timerRef.current`), and "a promise" is what the type checker says. There is no folder exemption: a `modules/` file is judged by its structure like any other (the API client starts its timeout timer and clears it in `finally`, in the same function).
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
-## `starci-fe/timer-needs-effect-cleanup`
+## `starci-fe/effect-subscription-needs-cleanup`
 
-`setTimeout` and `setInterval` live in an effect whose cleanup clears them.
+Inside a `useEffect` / `useLayoutEffect` callback and inside the subscribe function of `useSyncExternalStore`, everything that keeps running after the callback returns is released by the cleanup the callback returns, against the same handle, target and listener:
+
+| Started | Released by the returned cleanup |
+| --- | --- |
+| `setTimeout` / `setInterval` (the handle) | `clearTimeout(id)` / `clearInterval(id)` on the same handle (variable, ref member, module `let`, or a list drained with `forEach(clearTimeout)`) |
+| `requestAnimationFrame` (the id) | `cancelAnimationFrame(id)` |
+| `target.addEventListener(type, listener)` | `target.removeEventListener(type, listener)` with the same target, type and listener binding; an inline listener cannot be removed; or `{ signal }` with `controller.abort()` |
+| `new ResizeObserver` / `IntersectionObserver` / `MutationObserver` that is `.observe`d | `observer.disconnect()` |
+| `new WebSocket` / `EventSource` / `BroadcastChannel` | `connection.close()` |
+| a call returning a subscription object (its type has `unsubscribe`, `off` or `close`) | that method on the stored object |
+
+The cleanup may be a returned function, a named function that is returned, or may call a same-file function that releases. Outside an effect, a timer or frame is accepted only when the function that starts it also releases it (the API client's `try { ... } finally { clearTimeout(id) }`, the `subscribe` that returns its own unsubscribe); a listener started outside an effect is not judged. A function-returning unsubscribe (`const off = on(handler)`) is not decided here: the checker cannot tell it from any other callback.
 
 **Invalid** (`src/components/blocks/Feed/component.tsx`)
 
@@ -46,7 +57,7 @@ const subscribe = (listener: () => void) => {
 
 ## `starci-fe/no-data-fetch-in-effect`
 
-No `await`, `fetch` or `.then` inside a `useEffect`; read through SWR or a server reader.
+An effect body starts no promise: no `await`, `fetch`, `.then`, `void load()`, `mutate()` or `refresh()`; read through SWR or a server reader. The call is judged when it runs synchronously in the body (an immediately-invoked function counts); a promise started inside a listener or timer callback the effect registers, or in the cleanup, is that callback's work. A call is a load when its type is a promise, when it is `.then`-ed, or when it is `void`-ed and untyped; a platform promise other than `fetch` (`audio.play()`, `clipboard.writeText()`) is not a data load. Data freshness comes from the SWR key: an SWR `mutate()` or `refresh()` called directly in the effect body is a finding too; run it from the event that changed the data (a handler, a socket message).
 
 **Invalid** (`src/components/blocks/Feed/component.tsx`)
 

package/docs/lint-escape-hatch.md

@@ -2,7 +2,7 @@
 
 Law module: `lint-escape-hatch.mjs`. Catalogue: R18 HFS_INLINE_SUPPRESSION.
 
-No `eslint-disable` (line, next-line, block), `eslint-enable`, `eslint-env`, inline `eslint rule: ...` config, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, and no retired `vn-ok:` pragma. `noInlineConfig` makes a directive ineffective, this rule makes it a finding, and `reportUnusedDisableDirectives` reports a leftover that suppresses nothing. The rule covers `src/**`, specs and the e2e tree.
+No `eslint-disable` (line, next-line, block), `eslint-enable`, `eslint-env`, inline `eslint rule: ...` config, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, no retired `vn-ok:` pragma, and no `NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `v8 ignore`, `prettier-ignore` or `stylelint-disable` comment. `noInlineConfig` makes a directive ineffective, this rule makes it a finding, and `reportUnusedDisableDirectives` reports a leftover that suppresses nothing. The rule covers `src/**`, specs and the e2e tree.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
@@ -15,6 +15,8 @@ Source cannot change its own lint or type-check policy, and the vn-ok pragma is
 ```ts
 // eslint-disable-next-line no-console
 // @ts-ignore
+// NOSONAR
+/* istanbul ignore next */
 const s = "x" // vn-ok: reason
 ```
 

package/docs/next-conventions.md

@@ -204,3 +204,29 @@ router.push(routes.newWorkspace())
 **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.
 
 **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.
+
+## `starci-fe/i18n-stack-in-one-module`
+
+next-intl's routing, navigation, request config and middleware factories are called only in the i18n package (or the only app's `modules/i18n`).
+
+`defineRouting` (`next-intl/routing`), `createNavigation` (`next-intl/navigation`), `getRequestConfig` (`next-intl/server`) and `createMiddleware` (`next-intl/middleware`), resolved by the import that binds the called name (a renamed import or a namespace member counts), are called only in a file of slot `fe.package.i18n` (`packages/<family>-i18n`, exporting `createAppI18n`), or in a `fe.modules.i18n` file of a repository that declares exactly one app. In a multi-app repository each app's `modules/i18n` calls the package factory. It sits beside `no-second-i18n-stack`, which refuses another i18n library at its import; this rule refuses a second copy of next-intl's own stack.
+
+**Invalid** (`apps/web/src/modules/i18n/request.ts`, a repository with two apps)
+
+```ts
+import { getRequestConfig } from "next-intl/server"
+export default getRequestConfig(async () => ({ locale: "vi", messages: {} }))
+```
+
+**Valid** (`apps/web/src/modules/i18n/index.ts`)
+
+```ts
+import { createAppI18n } from "@nivo/i18n"
+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.
+
+**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 đó.

package/docs/size-growth.md

@@ -0,0 +1,29 @@
+# Size growth
+
+Law module: `size-growth.mjs`. Catalogue: R20 HFS_SIZE_GROWTH.
+
+A source file has a line budget, `ruleParams.fe.fileLines` of `knowledge/hfs/slots.yaml`, read through the slot view `hfsOf(context).ruleParams` (the package ships its own copy of the manifest in `runtime/`). A file over the budget may not be new and may not be longer than it was at the parent commit; a file within the budget is never a finding. The rule takes no option, there is no baseline file and no allowlist: the record is the repository's own history. `*.d.ts` declaration files are not governed.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/file-size-growth`
+
+A source file over the budget is neither new nor longer than its recorded size.
+
+**Invalid** (`src/components/Card/index.tsx`)
+
+```ts
+// a new file with more lines than the budget, or an existing file over the budget that gained a line
+```
+
+**Valid** (`src/components/Card/index.tsx`)
+
+```ts
+// a file within the budget, or an oversized file that stayed the same size or shrank
+```
+
+**Finding code:** `HFS_SIZE_GROWTH`
+
+**Vì sao (why):** `<file>` vượt ngân sách dòng: file mới đã dài quá mức, hoặc file cũ dài hơn bản ở commit cha. Mỗi file phải nhỏ để một người đọc hết và một bài test phủ hết.
+
+**Cách sửa:** Tách phần mới sang file riêng theo trách nhiệm; một file đã vượt ngân sách chỉ được giữ nguyên hoặc ngắn lại.

package/docs/spec-quality.md

@@ -52,18 +52,18 @@ import { Chip } from "./Chip"
 
 ## `starci-fe/no-barrel-spec`
 
-No `index.test.ts` beside an `index.ts` barrel.
+No `index.spec.ts(x)` beside an `index.ts(x)` that holds only imports and re-exports. The sibling is read and parsed: an `index.ts` that declares a function, class or value (implementation) may have its spec; a missing sibling is no finding.
 
-**Invalid** (`src/hooks/index.test.ts`)
+**Invalid** (`src/hooks/index.spec.ts`, beside `src/hooks/index.ts` = `export * from "./useFeed"`)
 
 ```ts
-// file: src/hooks/index.test.ts
+// file: src/hooks/index.spec.ts
 ```
 
-**Valid** (`src/hooks/feed/useFeed.test.ts`)
+**Valid** (`src/modules/browser-storage/index.spec.ts`, beside an `index.ts` that declares `createStore` and exports two stores)
 
 ```ts
-// file: src/hooks/feed/useFeed.test.ts
+// file: src/modules/browser-storage/index.spec.ts
 ```
 
 **Finding code:** `FE_SPEC_QUALITY`
@@ -118,7 +118,7 @@ it("a11y", async () => { expect(await axe(container)).toHaveNoViolations() })
 
 ## `starci-fe/no-mocked-translations`
 
-A spec renders with the real catalogue; it never mocks `next-intl`.
+A spec renders with the real catalogue; it never mocks `next-intl`. A `vi.mock("next-intl/server", factory)` in the spec of a server helper (no provider exists for it) is allowed when the factory - or a `vi.hoisted` block it reads - uses the app's real catalogue (an import that resolves into `modules/i18n/messages/`); a literal or key-echoing server mock, an automock, and any mock of the client `next-intl` stay findings.
 
 **Invalid** (`any spec`)
 
@@ -132,8 +132,16 @@ vi.mock("next-intl", () => ({}))
 render(<NextIntlClientProvider messages={messages} locale="vi" />)
 ```
 
+```ts
+import messages from "@/modules/i18n/messages/vi.json"
+vi.mock("next-intl/server", async () => {
+  const { createTranslator } = await import("next-intl")
+  return { getTranslations: async () => createTranslator({ locale: "vi", messages }) }
+})
+```
+
 **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.
+**Cách sửa:** Component client: render trong `NextIntlClientProvider` với `messages/<locale>.json` thật. Helper server (`next-intl/server`): factory của mock dựng translator từ catalog thật (`createTranslator` với `modules/i18n/messages/<locale>.json`).

package/docs/status-colors.md

@@ -0,0 +1,32 @@
+# Status colours: text and icons take the soft pair
+
+Law module: `status-colors.mjs`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
+
+A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.mjs`, which is generated from the grammar with the stylelint vocabulary.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/status-text-uses-soft-foreground`
+
+No class that paints text, an icon or a text decoration with a solid status tone: `text-<tone>`, `fill-<tone>`, `stroke-<tone>`, `decoration-<tone>` (with any variant, opacity or `!`), read from `className`/`class`, from `cn()`/`clsx()` arguments, conditionals, arrays, constants and `classes` entries.
+
+**Invalid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="text-success" />
+<svg className={cn("size-4", ok && "fill-danger")} />
+```
+
+**Valid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="bg-success-soft text-success-soft-foreground" />
+<button className="bg-success text-success-foreground" />
+<div className="border-danger ring-2 ring-warning" />
+```
+
+**Finding code:** `FE_STYLE_TOKEN_ONLY`
+
+**Vì sao (why):** `<file>` tô chữ hoặc icon bằng tông trạng thái đặc (`<what>`, ví dụ `text-success`). Tông đặc là màu nền; dùng làm màu chữ nó đọc dưới 4.5:1 trên nền trang.
+
+**Cách sửa:** Đổi thành cặp mềm: `text-<tông>-soft-foreground` (kèm `bg-<tông>-soft` nếu nằm trên nền nhạt); tông đặc chỉ dùng với `bg-<tông>` và `text-<tông>-foreground`.

package/docs/translation.md

@@ -33,6 +33,8 @@ User-facing text comes from a `next-intl` catalogue through `t()`, at every tier
 <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`)
@@ -43,6 +45,8 @@ const o = { title: "Your courses" }
 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()`.

package/docs/transport.md

@@ -2,13 +2,13 @@
 
 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/`.
+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 app's single `fetch` lives in `modules/api/client.ts`.
+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`)
 
@@ -24,9 +24,9 @@ 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.
+**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 app và nhận `Outcome<T>`; không tự gọi `fetch`.
+**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`
 
@@ -74,7 +74,7 @@ export const request = (token: string) => token
 
 ## `starci-fe/client-maps-auth-to-refused`
 
-`modules/api/client.ts` handles 401 and 403 and produces `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`)
 
@@ -86,14 +86,14 @@ const r = await fetch(u, { signal })
 
 ```ts
 const r = await fetch(u, { signal })
-if (r.status === 401 || r.status === 403) return { kind: "refused" }
+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 đổi 401/403 thành `refused`, nên trạng thái "cần đăng nhập" không bao giờ đạt được.
+**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 401/403 trả `{ kind: "refused" }` trong client.
+**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`
 
@@ -119,7 +119,7 @@ if (!res.ok) return toOutcome(res.status)
 
 ## `starci-fe/no-hand-typed-wire`
 
-Wire types come from the contract copy via codegen; responses are not cast.
+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`)
 
@@ -131,6 +131,8 @@ const x = (await res.json()) as Course
 
 ```ts
 import type { CourseQuery } from "../__generated__/graphql"
+const raw = (await res.json()) as unknown
+const x: CourseQuery = parse(raw)
 ```
 
 **Finding code:** `FE_WIRE_GENERATED`
@@ -166,3 +168,28 @@ switch (outcome.kind) {
 **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/e2e-shape.mjs

@@ -2,7 +2,7 @@
  * The rules that hold `e2e-shape.md` (HFS R66, `FE_E2E_SHAPE`).
  *
  * THESE RULES GOVERN THE E2E TREE, NOT `src/`. `starciFeConfig` attaches them to `e2e/**` and
- * `playwright.config.*`; every rule here also scopes itself by path, so a config that reaches it by
+ * `playwright.config.*`; every rule here also scopes itself by HFS slot (tier e2e, the Playwright config role), so a config that reaches it by
  * mistake governs nothing it should not.
  *
  * WHY THE SHAPE IS FIXED. An e2e suite is the only proof that the whole app works, and it is run by
@@ -16,9 +16,7 @@
  * architecture machine reads it); that the specs pass is the run itself.
  */
 
-import { isE2eFile } from "./lib/scope.mjs"
-import { baseName } from "./lib/scope.mjs"
-import { normalizePath } from "./lib/path.mjs"
+import { baseName, classOf, fileOf, inSlot, isE2eSource, roleOfFile } from "./lib/scope.mjs"
 
 /** The three viewports every e2e project set covers, as `width x height`. */
 export const VIEWPORTS = Object.freeze(["1440x900", "768x1024", "390x844"])
@@ -26,11 +24,11 @@ export const VIEWPORTS = Object.freeze(["1440x900", "768x1024", "390x844"])
 /** A file that reads like a spec, by any of the common spellings. */
 const SPEC_LIKE = /(?:\.|-)(?:e2e-)?(?:spec|test)\.[cm]?tsx?$/
 
-/** The one legal spec path: `e2e/<area>/<name>.e2e-spec.ts`. */
-const SPEC_PATH = /(?:^|\/)e2e\/[^/]+\/[^/]+\.e2e-spec\.ts$/
+/** A helper file that is named as a spec. */
+const E2E_SPEC_NAME = /\.e2e-spec\./
 
-/** Helper folders: not specs, and never spec-named. */
-const HELPER_PATH = /(?:^|\/)e2e\/(?:support|fixtures)\//
+/** The slots of the e2e tree: the specs (`fe.e2e`) and their helpers (`fe.e2e-support`). */
+const E2E_SLOTS = ["fe.e2e", "fe.e2e-support"]
 
 /** An absolute filesystem path: a drive, a UNC share, or a well-known root. */
 const ABSOLUTE_PATH = /^(?:[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|tmp|mnt|var|opt|etc|root|d|c)\/)/
@@ -77,15 +75,14 @@ export const e2eSpecLocation = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!/(?:^|\/)e2e\//.test(file)) return {}
-    const name = baseName(file)
-    const helper = HELPER_PATH.test(file)
-    const specLike = SPEC_LIKE.test(name)
-    const legal = SPEC_PATH.test(file) && !helper
-    if ((specLike && !legal) || (helper && /\.e2e-spec\./.test(name))) {
-      return { Program: (node) => context.report({ node, messageId: "location", data: { name } }) }
-    }
+    const name = baseName(fileOf(context))
+    const found = classOf(context)
+    // A helper slot (`fe.e2e-support`) owns no spec: a helper named like one is a spec in the wrong place.
+    const helperNamedSpec = inSlot(context, "fe.e2e-support") && E2E_SPEC_NAME.test(name)
+    // A spec-looking file no slot owns but that sits inside the e2e tree (the nearest slot is an e2e slot, matched past the repository root)
+    // is a spec off the one place `fe.e2e` gives it. A file outside the e2e tree is not this rule's business.
+    const misplacedSpec = found.status === "no-slot" && E2E_SLOTS.includes(found.nearest?.slot) && found.nearest.matchedDepth >= 1 && SPEC_LIKE.test(name)
+    if (helperNamedSpec || misplacedSpec) return { Program: (node) => context.report({ node, messageId: "location", data: { name } }) }
     return {}
   },
 }
@@ -104,7 +101,7 @@ export const e2eNoAbsolutePath = {
     },
   },
   create(context) {
-    if (!isE2eFile(context.filename || context.getFilename())) return {}
+    if (!isE2eSource(context)) return {}
     const check = (node, text) => {
       if (typeof text === "string" && ABSOLUTE_PATH.test(text)) context.report({ node, messageId: "absolute", data: { path: text } })
     }
@@ -135,7 +132,7 @@ export const e2eNoDocker = {
     },
   },
   create(context) {
-    if (!isE2eFile(context.filename || context.getFilename())) return {}
+    if (!isE2eSource(context)) return {}
     return {
       ImportDeclaration(node) {
         if (DOCKER_MODULE.test(String(node.source.value))) context.report({ node, messageId: "docker" })
@@ -194,7 +191,7 @@ export const e2eNoCrossRepoWrite = {
     },
   },
   create(context) {
-    if (!isE2eFile(context.filename || context.getFilename())) return {}
+    if (!isE2eSource(context)) return {}
     const source = context.sourceCode || context.getSourceCode()
     return {
       CallExpression(node) {
@@ -230,7 +227,7 @@ export const e2eNoSkip = {
     },
   },
   create(context) {
-    if (!isE2eFile(context.filename || context.getFilename())) return {}
+    if (!isE2eSource(context)) return {}
     return {
       CallExpression(node) {
         const callee = node.callee
@@ -267,7 +264,7 @@ export const e2eTypedHelpers = {
     },
   },
   create(context) {
-    if (!isE2eFile(context.filename || context.getFilename())) return {}
+    if (!isE2eSource(context)) return {}
     const checkParams = (node) => {
       if (!isModuleLevel(node)) return
       for (const parameter of node.params) {
@@ -308,7 +305,7 @@ export const playwrightViewports = {
     },
   },
   create(context) {
-    if (!/^playwright\.config\.[cm]?[jt]s$/.test(baseName(context.filename || context.getFilename()))) return {}
+    if (roleOfFile(context) !== "playwright") return {}
     const seen = new Map()
     return {
       Property(node) {

package/env-owner.mjs

@@ -67,7 +67,7 @@ export const noEnvOutsideConfig = {
   },
   create(context) {
     const filename = context.filename || context.getFilename()
-    if (isConfigModule(filename) || isSpecFile(filename)) return {}
+    if (isConfigModule(context) || isSpecFile(filename)) return {}
     return {
       MemberExpression(node) {
         if (isEnvObject(node)) context.report({ node, messageId: "env" })