@starci/eslint-canon-fe 5.1.2 → 6.0.0

package/lib/react.mjs

@@ -0,0 +1,28 @@
+/**
+ * React hooks of the front-end canon, decided by the import: a call is `useEffect` when its callee is the `useEffect`
+ * export of `react` (named import, alias, default or namespace member), not when something is spelled that way.
+ */
+import { importOf, unwrap } from "./bindings.mjs"
+
+/** The hooks that run work after render and may return its cleanup. */
+export const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect"])
+
+/**
+ * The React export a call invokes, or null when the callee is not an export of `react`.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} call - An ESTree call expression.
+ * @returns {string|null} The export name (`useEffect`, `useSyncExternalStore`, ...).
+ */
+export const reactHookOf = (context, call) => {
+  const callee = unwrap(call.callee)
+  if (callee.type === "Identifier") {
+    const from = importOf(context, callee)
+    return from && from.source === "react" && from.imported ? from.imported : null
+  }
+  if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier") {
+    const from = importOf(context, callee.object)
+    return from && from.source === "react" && from.imported === null ? callee.property.name : null
+  }
+  return null
+}

package/lib/scope.mjs

@@ -6,31 +6,74 @@
  * environment, and the disagreement shows up as a finding nobody can satisfy.
  */
 
+import { dirname, join, resolve } from "node:path"
+import { hfsOf } from "./hfs.mjs"
 import { normalizePath } from "./path.mjs"
 
-/** A spec or test file - it asserts about production shapes rather than being one. */
-export const isSpecFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx|mts|cts)$/.test(normalizePath(filename))
+/**
+ * The HFS slot id of the file being linted, read from the slot view (`settings.starci.hfs`).
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {string | null} The slot id, or null when no slot owns the file.
+ */
+export const slotOfFile = (context) => hfsOf(context).slotOf(context.filename || context.getFilename())
 
-/** Product source: under `src/`, and not a spec. */
-export const isProductFile = (filename) => {
-  const file = normalizePath(filename)
-  return file.includes("/src/") && !isSpecFile(file)
-}
+/**
+ * True when the file being linted sits in one of the given slots.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {...string} ids - Slot ids.
+ * @returns {boolean} Whether the file's slot is one of them.
+ */
+export const inSlot = (context, ...ids) => ids.includes(slotOfFile(context))
+
+/** The filename a rule is linting. */
+export const fileOf = (context) => context.filename || context.getFilename()
+
+/** The classification of the linted file from the slot view: `{ slot, root, bindings, kind?, role? }` or a no-slot status. */
+export const classOf = (context) => hfsOf(context).classify(fileOf(context))
+
+/** The tier of the linted file in the import direction matrix (`route`, `feature`, `components`, `hooks`, `foundation`, `modules`, `transport`, `e2e`, `package`, `none`), or null when no slot owns it. */
+export const tierOfFile = (context) => hfsOf(context).tierOf(fileOf(context))
+
+/** The folder kind the slot reports for the linted file (a component layer, a feature kind), or null. */
+export const kindOfFile = (context) => classOf(context).kind ?? null
+
+/** The role the slot reports for the linted file (`entry`, `drawing`, `styles`, `shared`, `page`, `layout`, ...), or null. */
+export const roleOfFile = (context) => classOf(context).role ?? null
+
+/**
+ * A spec or test file - it asserts about production shapes rather than being one. The slots define a spec by its name
+ * (`allows: "*.spec.tsx"`), so this stays a file-name test.
+ */
+export const isSpecFile = (filename) => /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(normalizePath(filename))
+
+/** The tiers of product source: everything a slot places in an app's route, feature, component, hook or module tiers and in a shared package. */
+const PRODUCT_TIERS = new Set(["route", "feature", "components", "hooks", "foundation", "modules", "transport", "package"])
+
+/** Product source: a file of a product tier, and not a spec. */
+export const isProductSource = (context) => PRODUCT_TIERS.has(tierOfFile(context)) && !isSpecFile(fileOf(context))
 
-/** The e2e tree: `e2e/**` and the Playwright config beside it. */
-export const isE2eFile = (filename) => {
-  const file = normalizePath(filename)
-  return /(?:^|\/)e2e\//.test(file) || /(?:^|\/)playwright\.config\.[cm]?[jt]s$/.test(file)
+/** A file of a component tier: slot `fe.components` or `fe.package.ui`, inside one of its layer folders (blocks, composites, branches, leaves). */
+export const isComponentFile = (context) => inSlot(context, "fe.components", "fe.package.ui") && kindOfFile(context) !== null
+
+/** True when the given file (an absolute or repo-relative name, e.g. where an import resolves to) sits in a component layer of slot `fe.components` or `fe.package.ui`. */
+export const isComponentPath = (context, file) => {
+  const found = hfsOf(context).classify(file)
+  return (found.slot === "fe.components" || found.slot === "fe.package.ui") && found.kind !== undefined
 }
 
-/** The one place that may read the environment. */
-export const isConfigModule = (filename) => /\/modules\/config\//.test(normalizePath(filename))
+/** The e2e tree (tier `e2e`: `fe.e2e`, `fe.e2e-support`) and the Playwright config (role `playwright` of `fe.tool-config`). */
+export const isE2eSource = (context) => tierOfFile(context) === "e2e" || roleOfFile(context) === "playwright"
+
+/** The one place that may read the environment: slot `fe.modules.config`. */
+export const isConfigModule = (context) => inSlot(context, "fe.modules.config")
 
-/** The one place that may call `fetch`. */
-export const isApiClient = (filename) => /\/modules\/api\/client\.[cm]?tsx?$/.test(normalizePath(filename))
+/** The one place that may call `fetch`: slot `fe.transport.client` (one-app repository) or `fe.package.api.client` (shared package). */
+export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client")
 
-/** The route files Next mounts as a segment slot. */
-export const ROUTE_SLOTS = ["page", "layout", "template", "loading", "not-found", "default", "route"]
+/** The file that may declare the one Outcome union: slot `fe.transport.outcome` or `fe.package.api.outcome`. */
+export const isOutcomeModule = (context) => inSlot(context, "fe.transport.outcome", "fe.package.api.outcome")
 
 /** The basename of a path without directories. */
 export const baseName = (filename) => normalizePath(filename).split("/").pop() ?? ""
@@ -38,5 +81,62 @@ export const baseName = (filename) => normalizePath(filename).split("/").pop() ?
 /** The file name with its extension removed. */
 export const stem = (filename) => baseName(filename).replace(/\.[cm]?[jt]sx?$/, "")
 
-/** The component tiers a workspace package holds directly under `src/` (`slots.yaml` `fe.package.ui`). */
-export const PACKAGE_TIERS = ["composites", "branches", "leaves"]
+/**
+ * The references in the file that resolve to no declaration of the file, i.e. to a global (`fetch`, `Request`, `window`).
+ * An import, a parameter, a local `const fetch` binds the name and is not one; a type-position use is not a value reference.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {Set<string>} names - The global names to look for.
+ * @returns {Array<object>} The ESTree identifiers that reference such a global as a value.
+ */
+export const globalReferences = (context, names) => {
+  const sourceCode = context.sourceCode ?? context.getSourceCode()
+  const found = []
+  const visit = (scope) => {
+    for (const reference of scope.references) {
+      if (!names.has(reference.identifier.name) || reference.isValueReference === false) continue
+      if (!reference.resolved || reference.resolved.defs.length === 0) found.push(reference.identifier)
+    }
+    scope.childScopes.forEach(visit)
+  }
+  visit(sourceCode.scopeManager.globalScope)
+  return found
+}
+
+/**
+ * Where an import specifier of the linted file points, as an absolute path without an extension: a relative specifier, or `@/`
+ * from the owning app's `src/` (the app directory is the directory part of slot `fe.app.next`). Null for a package or a file no app owns.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {string} specifier - The module specifier.
+ * @returns {string | null} The absolute path, or null.
+ */
+export const resolveImport = (context, specifier) => {
+  const hfs = hfsOf(context)
+  const file = fileOf(context)
+  if (specifier.startsWith(".")) return resolve(dirname(file), specifier)
+  if (!specifier.startsWith("@/")) return null
+  const app = hfs.classify(file).bindings?.app
+  if (app === undefined) return null
+  const appDirectory = hfs.slot("fe.app.next").path.split("/{")[0].replace("<app>", app)
+  return join(hfs.repoRoot, appDirectory, "src", specifier.slice(2))
+}
+
+/**
+ * The classification of the file an import specifier resolves to, trying the extensions a module file has. Null when the
+ * specifier resolves to no path.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {string} specifier - The module specifier.
+ * @returns {object | null} The slot classification (`{ slot, root, role, ... }`) of the first candidate a slot owns.
+ */
+export const classifyImport = (context, specifier) => {
+  const target = resolveImport(context, specifier)
+  if (target === null) return null
+  const hfs = hfsOf(context)
+  // The specifier names no extension: try the ones a module file has and take the candidate a slot gives a role, else the first a slot owns.
+  const owned = [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`, target]
+    .map((candidate) => hfs.classify(candidate))
+    .filter((found) => found.slot && found.status === "owned")
+  return owned.find((found) => found.role) ?? owned[0] ?? null
+}

package/lib/status-tones.generated.mjs

@@ -0,0 +1,9 @@
+// Generated by packages/stylelint/lib/write-vocabulary.mjs from packages/grammar/src. Do not edit: run `npm run vocabulary` in packages/stylelint.
+
+/** The status tones of the grammar: each has a solid pair and a soft pair (`--<tone>-soft`, `--<tone>-soft-foreground`). */
+export const STATUS_TONES = [
+  "success",
+  "warning",
+  "danger",
+  "info",
+]

package/lib/types.mjs

@@ -0,0 +1,63 @@
+/**
+ * Type-aware helpers of the front-end canon: a rule asks what a node IS (its TypeScript type, the symbol an identifier
+ * resolves to, the module a declaration comes from), never what it is called. `starciFeConfig` turns typed linting on for
+ * the source tree (`parserOptions.projectService`), so these helpers refuse to run without the program instead of falling
+ * back to a name match.
+ */
+import ts from "typescript"
+
+/**
+ * The TypeScript services of the file being linted.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {{ program: object, checker: object, toTs: (node: object) => object }} The program, its checker and the ESTree to TS node map.
+ */
+export const typed = (context) => {
+  const services = context.sourceCode?.parserServices ?? context.parserServices
+  if (!services?.program || !services.esTreeNodeToTSNodeMap) {
+    throw new Error(`${context.id ?? "a starci-fe rule"} needs typed linting (parserOptions.projectService); lint through starciFeConfig, which turns it on`)
+  }
+  const program = services.program
+  return { program, checker: program.getTypeChecker(), toTs: (node) => services.esTreeNodeToTSNodeMap.get(node) }
+}
+
+/**
+ * True when the type of an expression is a promise (a thenable carrying a `then` method), after union members are read.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} node - An ESTree expression.
+ * @returns {boolean} Whether evaluating the node yields a promise.
+ */
+export const isPromiseValued = (context, node) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(node)
+  if (!tsNode) return false
+  const type = checker.getTypeAtLocation(tsNode)
+  const parts = type.isUnion?.() ? type.types : [type]
+  return parts.some((part) => Boolean(part.getProperty?.("then")))
+}
+
+/**
+ * The declarations the symbol of an identifier resolves to, after import aliases are followed.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @param {object} identifier - An ESTree identifier (or any node with a symbol).
+ * @returns {Array<object>} The TypeScript declarations (empty when the checker has no symbol).
+ */
+export const declarationsOf = (context, identifier) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(identifier)
+  if (!tsNode) return []
+  let symbol = checker.getSymbolAtLocation(tsNode)
+  if (!symbol) return []
+  if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+  return symbol.getDeclarations?.() ?? []
+}
+
+/**
+ * The forward-slash file name a declaration lives in.
+ *
+ * @param {object} declaration - A TypeScript declaration.
+ * @returns {string} Its source file name.
+ */
+export const fileOf = (declaration) => String(declaration.getSourceFile().fileName).split("\\").join("/")

package/lib/why.mjs

@@ -28,8 +28,8 @@ export const why = {
   },
   "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`.",
+    vi: "`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.",
+    fixVi: "Gọi client của repo và nhận `Outcome<T>`; không tự gọi `fetch`.",
   },
   "client-fetch-has-signal": {
     code: "FE_TRANSPORT_OWNER",
@@ -43,8 +43,8 @@ export const why = {
   },
   "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.",
+    vi: "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.",
+    fixVi: "Thêm nhánh `response.status === 401 || response.status === 403` trả `{ ok: false, kind: \"refused\" }` ngay trong client.",
   },
   "no-http-status-collapse": {
     code: "FE_HTTP_STATUS_COLLAPSE",
@@ -96,6 +96,11 @@ export const why = {
     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`.",
   },
+  "status-text-uses-soft-foreground": {
+    code: "FE_STYLE_TOKEN_ONLY",
+    vi: "`<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.",
+    fixVi: "Đổ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`.",
+  },
   "no-native-form-control": {
     code: "FE_NATIVE_FORM_CONTROL",
     vi: "`<tag>` thô ở `<file>`. Dùng renderer của grammar.",
@@ -163,7 +168,7 @@ export const why = {
   },
   "no-barrel-spec": {
     code: "FE_SPEC_QUALITY",
-    vi: "Spec `<file>` đặt cạnh một barrel. Barrel không có hành vi để test.",
+    vi: "Spec `<file>` đặt cạnh một `index` chỉ có import và re-export (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": {
@@ -179,7 +184,7 @@ export const why = {
   "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.",
+    fixVi: "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`).",
   },
   "no-inline-lint-config": {
     code: "HFS_INLINE_SUPPRESSION",
@@ -221,15 +226,15 @@ export const why = {
     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": {
+  "effect-subscription-needs-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 đó.",
+    vi: "`<what>` ở `<file>` (timer, frame, listener, observer, socket hoặc subscription) được effect hoặc `subscribe` khởi động nhưng cleanup trả về không giải phóng đúng handle/target/listener đó.",
+    fixVi: "Giữ handle và trả cleanup gọi `clearTimeout(id)`, `cancelAnimationFrame(id)`, `removeEventListener` cùng type và listener, `.disconnect()`, `.close()` hoặc `.unsubscribe()` trên đúng đối tượng.",
   },
   "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`.",
+    vi: "`useEffect` ở `<file>` khởi động một promise (`await`, `fetch`, `.then`, `void load()`, `mutate()`/`refresh()` gọi thẳng): không cache, không gộp request, không trạng thái loading/lỗi, không huỷ. Độ tươi của dữ liệu đến từ key của SWR, không đến từ effect.",
+    fixVi: "Đọc phía client bằng SWR gọi client của app (`hooks/`) với key theo thứ thay đổi; gọi `mutate()` từ sự kiện làm dữ liệu đổi (handler, message socket); phía route dùng server reader `modules/api/<domain>/read-*.ts`.",
   },
   "no-empty-catch": {
     code: "FE_SWALLOWED_ERROR",
@@ -276,6 +281,11 @@ export const why = {
     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.",
   },
+  "server-module-marks-server-only": {
+    code: "FE_SERVER_ONLY_MARK",
+    vi: "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\"`.",
+    fixVi: "Đặ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.",
+  },
   "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.",
@@ -301,4 +311,24 @@ export const why = {
     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`.",
   },
+  "one-outcome-union": {
+    code: "FE_HTTP_STATUS_COLLAPSE",
+    vi: "`<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>`.",
+    fixVi: "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.",
+  },
+  "i18n-stack-in-one-module": {
+    code: "FE_I18N_PLACEMENT",
+    vi: "`<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.",
+    fixVi: "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 đó.",
+  },
+  "no-raw-structural-element": {
+    code: "FE_NATIVE_FORM_CONTROL",
+    vi: "`<tag>` thô ở `<file>`. Cấu trúc trang và chữ được ghép từ component của grammar, không viết HTML thô.",
+    fixVi: "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ỗ.",
+  },
+  "file-size-growth": {
+    code: "HFS_SIZE_GROWTH",
+    vi: "`<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.",
+    fixVi: "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/lint-escape-hatch.mjs

@@ -8,6 +8,10 @@
  *   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
+ *   NOSONAR, @sonar-ignore                        - Sonar's own switches
+ *   istanbul ignore, c8 ignore, v8 ignore         - a line taken out of the coverage the gate reads
+ *   prettier-ignore                               - a region taken out of the formatter
+ *   stylelint-disable / -enable                   - a stylelint switch that reached a TS file
  *
  * 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
@@ -15,14 +19,10 @@
  * nothing is dead weight that reads as if it did.
  */
 
-import { isE2eFile, isProductFile, isSpecFile } from "./lib/scope.mjs"
-import { normalizePath } from "./lib/path.mjs"
+import { fileOf, isE2eSource, isProductSource, isSpecFile } from "./lib/scope.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)
-}
+const isGoverned = (context) => isProductSource(context) || isSpecFile(fileOf(context)) || isE2eSource(context)
 
 /**
  * Any directive that changes ESLint's active rule set inside a source file.
@@ -39,6 +39,13 @@ const ESLINT_DIRECTIVE = /^\s*eslint-(?:disable(?:-next-line|-line)?|enable|env)
 /** 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/
 
+/**
+ * A quality-tool switch other than ESLint's: Sonar honours `NOSONAR` anywhere in a comment (case-insensitively), so it is
+ * matched anywhere; the others are read by their tool from the start of the comment, so they are anchored there too.
+ */
+const TOOL_DIRECTIVE =
+  /\bNOSONAR\b|^\s*@sonar-ignore\b|^\s*(?:istanbul|c8|v8)\s+ignore\b|^\s*prettier-ignore(?:-start|-end)?\b|^\s*stylelint-(?:disable(?:-next-line|-line)?|enable)\b/i
+
 /** The retired second-language pragma. Present anywhere in a comment, it is a finding. */
 const RETIRED_PRAGMA = /\bvn-ok:/
 
@@ -53,18 +60,21 @@ export const noInlineLintConfig = {
         "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.",
+      tool:
+        "A Sonar, coverage, formatter or stylelint suppression (`NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `prettier-ignore`, `stylelint-disable`). It removes this code from a gate that is failing it for a reason, and the next reader cannot tell a measured exception from an avoided fix. Fix the code, or change the shared rule or the coverage threshold; 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 {}
+    if (!isGoverned(context)) 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 (TOOL_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "tool" })
           else if (RETIRED_PRAGMA.test(comment.value)) context.report({ node: comment, messageId: "pragma" })
         }
       },
@@ -81,11 +91,3 @@ export const rules = {
 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" })

package/loading.mjs

@@ -12,16 +12,10 @@
  * lint rule is for - the one nothing else will ever report.
  */
 
-import { normalizePath } from "./lib/path.mjs"
+import { classOf, fileOf, isComponentFile, isSpecFile } from "./lib/scope.mjs"
 
-/** The component tree; a placeholder in a test fixture is a fixture, not a second tree. */
-const isComponentFile = (filename) => normalizePath(filename).includes("/src/components/")
-
-/** A twin test may build a resting shape by hand to assert against it. */
-const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
-
-/** Product component source these rules govern. */
-const isGoverned = (filename) => isComponentFile(filename) && !isTestFile(filename)
+/** Product component source these rules govern: a component owner's file, and not a spec (a placeholder in a test fixture is a fixture, not a second tree). */
+const isGoverned = (context) => isComponentFile(context) && !isSpecFile(fileOf(context))
 
 /** A flag that means "waiting", in the spellings this codebase uses. */
 const WAITING_FLAG = /\bis(?:Loading|Skeleton|Pending)\b/
@@ -54,13 +48,12 @@ export const noRestingTwinComponent = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isGoverned(file)) return {}
-    const hit = file.match(/\/([A-Za-z0-9]*Skeleton)\/index\.tsx?$/) || file.match(/\/([A-Za-z0-9]*Skeleton)\.tsx?$/)
-    if (!hit || !TWIN_NAME.test(hit[1])) return {}
+    if (!isGoverned(context)) return {}
+    const owner = classOf(context)
+    if (owner.role !== "entry" || !TWIN_NAME.test(owner.bindings?.name ?? "")) return {}
     return {
       Program(node) {
-        context.report({ node, messageId: "twin", data: { name: hit[1] } })
+        context.report({ node, messageId: "twin", data: { name: owner.bindings.name } })
       },
     }
   },
@@ -82,7 +75,7 @@ export const noPlaceholderProp = {
     },
   },
   create(context) {
-    if (!isGoverned(context.filename || context.getFilename())) return {}
+    if (!isGoverned(context)) return {}
     return {
       JSXAttribute(node) {
         const name = node.name && node.name.type === "JSXIdentifier" ? node.name.name : null
@@ -122,7 +115,7 @@ export const noRestingBranchAtCallSite = {
     },
   },
   create(context) {
-    if (!isGoverned(context.filename || context.getFilename())) return {}
+    if (!isGoverned(context)) return {}
     const source = context.sourceCode || context.getSourceCode()
     /** Root element name of one arm, or null when the arm is not an element. */
     const armName = (expression) => {

package/naming.mjs

@@ -11,6 +11,10 @@
  * describes an action is not its business.
  */
 
+import { hfsOf } from "./lib/hfs.mjs"
+import { NEXT_RESERVED_EXPORTS } from "./lib/next.mjs"
+import { fileOf, inSlot, roleOfFile } from "./lib/scope.mjs"
+
 /** Parents that make a function declaration module-level rather than nested. */
 const MODULE_LEVEL_PARENTS = new Set(["Program", "ExportNamedDeclaration", "ExportDefaultDeclaration"])
 
@@ -86,10 +90,13 @@ export const noDirectConstAlias = {
     },
   },
   create(context) {
+    // A route segment file (slot `fe.route`, a role: page, layout, route, ...) is the one place Next dictates the exported name; `export const generateMetadata = x` is the contract.
+    const segmentFile = inSlot(context, "fe.route") && roleOfFile(context) !== null
     return {
       VariableDeclarator(node) {
         if (node.parent?.kind !== "const") return
         if (node.id?.type !== "Identifier" || node.init?.type !== "Identifier") return
+        if (segmentFile && NEXT_RESERVED_EXPORTS.has(node.id.name) && node.parent.parent?.type === "ExportNamedDeclaration") return
         context.report({
           node: node.id,
           messageId: "alias",
@@ -149,8 +156,7 @@ export const noSecondLanguageInPath = {
     },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    const offending = segmentsOf(filename).find(
+    const offending = segmentsOf(hfsOf(context).relative(fileOf(context))).find(
       (segment) => SECOND_LANGUAGE_PATH.test(segment) || ROMANISED.includes(segment.replace(/[()[\]]/g, "")),
     )
     if (!offending) return {}