@starci/eslint-canon-fe 9.2.0 → 9.4.0

package/dist/lib/why.js

@@ -0,0 +1,350 @@
+/**
+ * The "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 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, `en` the English source of the headline with `<file>` /
+ * `<what>` placeholders the reader fills from the ESLint location, `fix` the one sentence "what do I
+ * do now". The owner reads both in Vietnamese through the declared message catalog: the `en` and
+ * `fix` strings are the keys of `modules/i18n/messages/canon.yaml`, so `translator('vi')(entry.en)` and
+ * `translator('vi')(entry.fix)` hand back the Vietnamese of the same sentence.
+ *
+ * Every rule that carries a catalogue id (R18, R22, R49-R59, R60-R62, R65, the fe-stack catalog) 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, en: string, fix: string }} Why */
+/** @type {Record<string, Why>} */
+export const why = {
+    "selection-fill-no-check": {
+        code: "FE_NESTED_VARIANT",
+        en: "`<file>` adds a check indicator to a navigation-like single-select list.",
+        fix: 'Set selectionIndicator="none" and let the row fill carry selection.',
+    },
+    "no-grammar-internal-selector": {
+        code: "FE_GRAMMAR_LAYOUT_ONLY",
+        en: "`<file>` targets a Grammar internal class from application styles.",
+        fix: "Use the Grammar public props and slots; keep internal selectors inside Grammar.",
+    },
+    "divider-full-bleed": {
+        code: "FE_DIVIDER_FULL_BLEED",
+        en: "`<file>` insets a horizontal Grammar divider with wrapper padding.",
+        fix: "Move horizontal padding to the sibling content bands so the divider reaches both surface edges.",
+    },
+    "button-intent-required": {
+        code: "FE_BUTTON_INTENT_REQUIRED",
+        en: "`<file>` renders a Button or IconButton without the command's intent.",
+        fix: "Declare intent from the command's consequence and rank so Grammar supplies its variant.",
+    },
+    "control-height": {
+        code: "FE_CONTROL_HEIGHT",
+        en: "`<file>` picks a larger control size or mixes control sizes in one row.",
+        fix: "Omit size so Grammar draws the one 40px control height; use sm only for every control of an item or dense toolbar row, and lg only for a landing hero call to action.",
+    },
+    "no-grammar-shim": {
+        code: "FE_GRAMMAR_SHIM",
+        en: "`<file>` re-exports a Grammar component under the app's own name.",
+        fix: "Delete the shim and import the component from the Grammar where it is rendered; report the Grammar defect the shim worked around (the op files blocked) so the Grammar fixes it.",
+    },
+    "button-no-variant": {
+        code: "FE_BUTTON_NO_VARIANT",
+        en: "`<file>` chooses a Button or IconButton variant directly.",
+        fix: "Replace variant with intent and let Grammar resolve placement and visual treatment.",
+    },
+    "destructive-confirm-in-dialog": {
+        code: "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG",
+        en: "`<file>` renders a final destructive press outside its confirmation dialog.",
+        fix: "Place the destructive confirm inside the same-file AlertDialog or ConfirmDialog; use entry on its trigger.",
+    },
+    "single-commit-per-render": {
+        code: "FE_SINGLE_COMMIT_PER_RENDER",
+        en: "`<file>` renders more than one commit in the same component render path.",
+        fix: "Keep the next action as commit and assign the other commands their consequence-based intents.",
+    },
+    "no-commit-in-collection-item": {
+        code: "FE_NO_COMMIT_IN_COLLECTION_ITEM",
+        en: "`<file>` repeats a commit inside a collection item render.",
+        fix: "Use alternative for the item's next action and keep the enclosing view's commit unique.",
+    },
+    "nested-control-variant": {
+        code: "FE_NESTED_VARIANT",
+        en: "`<file>` sets a static Grammar field variant, or forces primary Tabs inside a painted surface.",
+        fix: "Omit the field or nested Tabs variant so Grammar supplies the default from its surface context.",
+    },
+    "no-app-surface-paint": {
+        code: "FE_GRAMMAR_LAYOUT_ONLY",
+        en: "`<file>` sets paint or typography in app CSS instead of composing Grammar's published components and props.",
+        fix: "Keep app CSS layout-only and compose a painted Grammar surface such as SurfaceCard.",
+    },
+    "no-list-panel-padding": {
+        code: "FE_LIST_PANEL_PADDING",
+        en: "`<file>` adds horizontal wrapper padding to a Grammar list or its section caption, stacking the content inset.",
+        fix: "Remove the wrapper padding and use ListBox inset=\"panel\" so headers, captions and rows share the panel content edge.",
+    },
+    "no-env-outside-config": {
+        code: "FE_ENV_OWNER",
+        en: "`<file>` reads an environment variable. Only `modules/config` may read env.",
+        fix: "Read the value from a typed export of `modules/config` instead of `process.env`.",
+    },
+    "no-hardcoded-endpoint-fallback": {
+        code: "FE_ENV_OWNER",
+        en: "`<file>` carries a hardcoded fallback for an address or a secret (`?? \"http://localhost…\"`). A variable missing in production must throw at config load, not silently point at a dev machine.",
+        fix: "Delete the fallback; let `modules/config` throw when a variable is missing in production.",
+    },
+    "fetch-only-in-api-client": {
+        code: "FE_TRANSPORT_OWNER",
+        en: "`<file>` reaches the back end outside the API layer: `fetch` (or `Request`, `EventSource`, `sendBeacon`, another HTTP library) outside `modules/api`, or Apollo, axios or socket.io-client outside its home (`modules/api`, `modules/api/rest`, `hooks/socketio`).",
+        fix: "Call an operation of `modules/api` (Apollo GraphQL, or axios in `modules/api/rest`) through its SWR hook in `hooks/swr`; listen to realtime through `hooks/socketio`.",
+    },
+    "client-fetch-has-signal": {
+        code: "FE_TRANSPORT_OWNER",
+        en: "`fetch` in `<file>` has no `signal`. Every request of the API layer must carry a timeout and an `AbortSignal`.",
+        fix: "Pass `signal` (`AbortSignal.timeout(...)` combined with the caller's signal).",
+    },
+    "no-shared-transport-state": {
+        code: "FE_TRANSPORT_OWNER",
+        en: "`<file>` holds shared state as `let`/`var` in the API layer. Token and locale must not sit in a singleton.",
+        fix: "Pass credential and locale as parameters or through context.",
+    },
+    "client-maps-auth-to-refused": {
+        code: "FE_HTTP_STATUS_COLLAPSE",
+        en: "The client in `<file>` has no branch comparing `response.status` with 401 and 403 and returning `{ kind: \"refused\" }`, so the \"sign-in required\" state is never reached.",
+        fix: "Add a `response.status === 401 || response.status === 403` branch returning `{ ok: false, kind: \"refused\" }` right inside the client.",
+    },
+    "no-failure-collapse": {
+        code: "FE_HTTP_STATUS_COLLAPSE",
+        en: "`<file>` merges every failure (an error HTTP response or a failed `Outcome`) into one branch or one empty value, so the reason is lost.",
+        fix: "Keep the reason: for an `Outcome` branch on the reason code; for an HTTP response turn the status code into an `Outcome` (`refused` for 401/403, `not-found`, `invalid`, `unavailable`). Do not use the server's raw error as the reason.",
+    },
+    "no-hand-typed-wire": {
+        code: "FE_WIRE_GENERATED",
+        en: "`<file>` hand-types a wire type, casts a response, or writes a GraphQL document outside the API layer. Use the types generated from `be/contracts/`.",
+        fix: "Run codegen from the be contract snapshot (`be/contracts/`) and import the generated types; write each GraphQL document in its operation file under `modules/api/graphql/queries` or `modules/api/graphql/mutations`.",
+    },
+    "use-client-only-at-boundary": {
+        code: "FE_CLIENT_BOUNDARY",
+        en: "`\"use client\"` in `<file>` (`<slot>` may not be a client component).",
+        fix: "Put `\"use client\"` on the `index.tsx` of an interactive block, a leaf, or `error.tsx`/`global-error.tsx`; keep layout and page as server components.",
+    },
+    "hooks-folder-holds-hooks-only": {
+        code: "FE_HOOKS_ARE_HOOKS",
+        en: "`<file>` inside `hooks/` is not a React hook, or is not a file its hooks family names. A call to the back end goes to `modules/api`, a helper to `<domain>.shared.ts`.",
+        fix: "One hook per `use*.ts` file under the name its family gives it (`hooks/swr/api/graphql/queries/useQuery<X>Swr.ts`, `hooks/rhf/use<X>Form.ts`, ...); a shared helper goes in `<domain>.shared.ts`; a back-end call is an operation of `modules/api`.",
+    },
+    "no-middleware-file": {
+        code: "FE_NEXT_CONVENTIONS",
+        en: "`<file>` uses the name `middleware`. From Next 16 the request gate is `proxy.ts` exporting `proxy`.",
+        fix: "Rename the file to `proxy.ts` and rename the export to `proxy`.",
+    },
+    "locale-segment-is-locale": {
+        code: "FE_I18N_PLACEMENT",
+        en: "File `<file>` sits under a locale segment that is not `[locale]`. There is one pattern: `next-intl`, `[locale]`, default `vi`.",
+        fix: "Rename the segment directory to `[locale]`.",
+    },
+    "no-second-i18n-stack": {
+        code: "FE_I18N_PLACEMENT",
+        en: "`<file>` imports a second i18n library. The app uses only `next-intl` through `modules/i18n`.",
+        fix: "Switch to `next-intl`; delete the other library.",
+    },
+    "html-lang-from-locale": {
+        code: "FE_I18N_LITERAL",
+        en: "`<html lang>` in `<file>` is a hardcoded string. The `lang` attribute must come from the `[locale]` segment.",
+        fix: "Use `lang={locale}` from the parameter of the `[locale]` layout.",
+    },
+    "no-hardcoded-copy": {
+        code: "FE_I18N_LITERAL",
+        en: "The text `\"<text>\"` in `<file>:<line>` does not go through `t()`.",
+        fix: "Move the sentence into `modules/i18n/messages/<locale>.json` and read it with `t(\"key\")`; no exceptions.",
+    },
+    "no-raw-brand-value": {
+        code: "FE_STYLE_TOKEN_ONLY",
+        en: "`<file>` uses a raw colour/length value (`<what>`). Colour and spacing come only from grammar tokens; brand colour lives only in `brand.css`.",
+        fix: "Use a grammar token class or variable; a colour value is declared only in `modules/brand/brand.css`.",
+    },
+    "no-native-form-control": {
+        code: "FE_NATIVE_FORM_CONTROL",
+        en: "Raw `<tag>` in `<file>`. Use the grammar renderer.",
+        fix: "Replace it with the grammar component; if none exists yet, add it to grammar instead of drawing it in place.",
+    },
+    "component-line-budget": {
+        code: "FE_SIZE_AND_STATE_BUDGET",
+        en: "`<file>` is `<n>` lines long, over the 300-line budget of a component.",
+        fix: "Split the drawing part from the data part and each area into its own unit.",
+    },
+    "unit-hook-budget": {
+        code: "FE_SIZE_AND_STATE_BUDGET",
+        en: "`<unit>` has `<n>` data hooks / `<m>` useState, over the budget of 6.",
+        fix: "Fold state that changes together into a reducer or a dedicated hook; split each data area into its own connection block.",
+    },
+    "no-hand-rolled-polling": {
+        code: "FE_SIZE_AND_STATE_BUDGET",
+        en: "`<unit>` hand-writes a poll loop (`setInterval` or a self-rescheduling `setTimeout`).",
+        fix: "Refresh through a data hook (`refreshInterval`) or a socket, one mechanism per resource.",
+    },
+    "no-inline-lint-config": {
+        code: "HFS_INLINE_SUPPRESSION",
+        en: "A comment disabling a rule sits at `<file>:<line>`. HFS does not allow in-place suppression - fix the code, or propose a rule change.",
+        fix: "Remove `eslint-disable`, `@ts-ignore` or `@ts-expect-error` and fix the cause.",
+    },
+    "no-double-cast": {
+        code: "FE_TYPE_ESCAPE",
+        en: "`<file>` casts through `unknown` (`as unknown as T`): the compiler forgets everything it knows right where the data enters.",
+        fix: "Narrow from `unknown` with a type guard or a parser; do not cast.",
+    },
+    "no-type-assertion": {
+        code: "FE_TYPE_ESCAPE",
+        en: "`<file>` uses `as T` or `<T>x`: an assertion the compiler cannot check. If it is wrong, the error lands in the user's browser.",
+        fix: "Narrow with a type guard, `in`, a discriminant or a parser where the data enters; use `satisfies` when you only mean to check a literal.",
+    },
+    "no-non-null-assertion": {
+        code: "FE_TYPE_ESCAPE",
+        en: "`<file>` uses `x!`: asserting a value is present without proving it.",
+        fix: "Handle the absent branch (`if`, `??`, an early return) or fix the type so the value cannot be absent.",
+    },
+    "no-explicit-any": {
+        code: "FE_TYPE_ESCAPE",
+        en: "`<file>` uses `any`: it switches off type checking for that value and for everything inferred from it.",
+        fix: "Use a real type, a generic, or `unknown` narrowed at the use site.",
+    },
+    "list-item-has-key": {
+        code: "FE_LIST_KEY",
+        en: "An element returned from `.map` in `<file>` has no `key`, so React identifies the row by position and the row loses state on delete or reorder.",
+        fix: "Add a `key` taken from the data's id; for a fragment use `<Fragment key={...}>`.",
+    },
+    "no-index-key": {
+        code: "FE_LIST_KEY",
+        en: "A `key` in `<file>` comes from the `.map` index or a randomly generated value; an index is a position, not an identity.",
+        fix: "Use the id the data carries (`key={row.id}`); never the index, `Math.random`, `Date.now`.",
+    },
+    "no-inline-literal-prop-in-list": {
+        code: "FE_LIST_KEY",
+        en: "A component in a `.map` in `<file>` receives an object or array literal as a prop: every row gets a new value every render, so memo never hits.",
+        fix: "Hoist the constant outside the component or build it once before `.map`.",
+    },
+    "effect-subscription-needs-cleanup": {
+        code: "FE_EFFECT_CLEANUP",
+        en: "`<what>` in `<file>` (timer, frame, listener, observer, socket or subscription) is started by an effect or `subscribe` but the returned cleanup does not release that same handle/target/listener.",
+        fix: "Keep the handle and return a cleanup calling `clearTimeout(id)`, `cancelAnimationFrame(id)`, `removeEventListener` with the same type and listener, `.disconnect()`, `.close()` or `.unsubscribe()` on the right object.",
+    },
+    "no-data-fetch-in-effect": {
+        code: "FE_EFFECT_FETCH",
+        en: "`useEffect` in `<file>` starts a promise (`await`, `fetch`, `.then`, `void load()`, `mutate()`/`refresh()` called directly): no cache, no request merging, no loading/error state, no abort. Freshness of data comes from the SWR key, not from an effect.",
+        fix: "Read with an SWR hook of `hooks/swr` over an operation of `modules/api`, keyed by what changes; call `mutate()` from the event that changes the data (handler, socket message).",
+    },
+    "no-empty-catch": {
+        code: "FE_SWALLOWED_ERROR",
+        en: "A `catch` or `.catch` in `<file>` does nothing: the error vanishes, no notice, no trace.",
+        fix: "Return a typed outcome carrying the cause, show an error state, or rethrow.",
+    },
+    "no-console": {
+        code: "FE_CONSOLE_CALL",
+        en: "`console.<method>` in `<file>`: it reaches no log pipeline and leaks internal detail to the user.",
+        fix: "Return a typed outcome, show an error state, or let the error reach `error.tsx`.",
+    },
+    "page-exports-metadata": {
+        code: "FE_PAGE_METADATA_MISSING",
+        en: "`<file>` is `page.tsx` but exports no `metadata` or `generateMetadata`; every page in the branch carries the same title.",
+        fix: "Export `metadata` (or `generateMetadata` when the title comes from data) with a title and description taken from the message catalog.",
+    },
+    "no-null-suspense-fallback": {
+        code: "FE_SUSPENSE_NULL_FALLBACK",
+        en: "`<Suspense>` in `<file>` has an empty `fallback`: the user sees a blank instead of a loading state.",
+        fix: "Pass the skeleton (loading state) of the very thing loading as the `fallback`.",
+    },
+    "navigation-from-intl": {
+        code: "FE_I18N_NAVIGATION",
+        en: "`<file>` imports `Link`, `useRouter`, `usePathname` or `redirect` from Next, which does not know the locale: the path loses the `[locale]` prefix.",
+        fix: "Import from the locale-aware public routes entry or shared i18n package, built from the one routing configuration.",
+    },
+    "no-native-anchor": {
+        code: "FE_I18N_NAVIGATION",
+        en: "`<a>` in `<file>` points at an internal route (reloads the whole page, loses the locale, loses prefetch) or opens a new tab without `rel`.",
+        fix: "Use the locale-aware Link with an href built by modules/routes; a _blank link adds rel=\"noopener noreferrer\".",
+    },
+    "use-intl-formatter": {
+        code: "FE_I18N_FORMATTER",
+        en: "`<file>` formats a number, money or a date with `toLocale*String`, `new Intl.*`, `toFixed`, a currency sign pasted into a template or a date library, instead of the next-intl formatter.",
+        fix: "Use `useFormatter()` (or `getFormatter()` on the server): `number(...)`, `dateTime(...)`, `relativeTime(...)`.",
+    },
+    "no-hardcoded-route": {
+        code: "FE_ROUTE_HARDCODED",
+        en: "`<file>` writes a route path inline at the call site; when the route moves, the copy points at a 404.",
+        fix: "Build the href with a function of `modules/routes` and use that same function everywhere.",
+    },
+    "client-no-server-import": {
+        code: "FE_CLIENT_SERVER_IMPORT",
+        en: "A client component in `<file>` imports code that exists only on the server (`server-only`, `next/headers`, a Node module, a server-only module).",
+        fix: "Read the data through an SWR hook of `hooks/swr` over an operation of `modules/api`; keep request-scoped server APIs in server components.",
+    },
+    "server-module-marks-server-only": {
+        code: "FE_SERVER_ONLY_MARK",
+        en: "Module `<file>` imports a server-only API (`next/headers`, `next/server`, `next-intl/server`, a Node module or an already server-only module) but does not open with `import \"server-only\"`.",
+        fix: "Make `import \"server-only\"` the file's first statement; route files (`page`, `layout`, `route`, `proxy`) are server components already and need none.",
+    },
+    "no-server-action": {
+        code: "FE_SERVER_ACTION_FORBIDDEN",
+        en: "`<file>` carries a `\"use server\"` directive: a Server Action, an endpoint the front end serves. The front end serves no API.",
+        fix: "Write it as a GraphQL mutation of the back end and call it through its operation in `modules/api` and its SWR hook in `hooks/swr`.",
+    },
+    "web-storage-only-in-modules": {
+        code: "FE_STORAGE_OUTSIDE_MODULES",
+        en: "`<file>` uses `localStorage`/`sessionStorage` outside `modules/`; storage does not exist on the server and throws when over quota.",
+        fix: "Put the read/write behind a hook or a module in `modules/` with a guard (`typeof window`, try/catch) and call it from the block.",
+    },
+    "no-dangerous-html": {
+        code: "FE_DANGEROUS_HTML",
+        en: "`dangerouslySetInnerHTML` on `<tag>` in `<file>`: any string becomes runnable HTML.",
+        fix: "Render content as elements; only a `<script>` carrying JSON-LD or theme code from an app constant may use it.",
+    },
+    "response-cookie-attributes": {
+        code: "FE_COOKIE_ATTRIBUTES",
+        en: "`<file>` writes a cookie through the Next response cookie without stating fixed `httpOnly`, missing `secure` or a `sameSite` that is not `lax`/`strict`.",
+        fix: "Pass one `as const` options constant of the module owning the cookie: `httpOnly: true` (`false` only for a cookie an optional script must read), `secure` from `modules/config`, `sameSite: \"lax\"` or `\"strict\"`.",
+    },
+    "props-fields-readonly": {
+        code: "FE_PROPS_MUTABLE",
+        en: "A props type of a component in `<file>` has a field or collection that is not `readonly`, so the component could write into what it is passed.",
+        fix: "Mark every field and index signature `readonly`, and write collections as `readonly T[]`, `readonly [A, B]` or `ReadonlyArray<T>`.",
+    },
+    "no-native-img": {
+        code: "FE_NATIVE_IMAGE",
+        en: "Raw `<img>` in `<file>`: it loads the original image and holds no space, so the page jumps when the image arrives.",
+        fix: "Use `Image` of `next/image` with `width` and `height` (or `fill` and `sizes`) and an `alt` from the catalog.",
+    },
+    "image-has-size": {
+        code: "FE_NATIVE_IMAGE",
+        en: "`Image` in `<file>` lacks `width` and `height` (or has `fill` without `sizes`): the browser cannot hold the space.",
+        fix: "Give both `width` and `height`, or `fill` inside a sized frame with `sizes`.",
+    },
+    "outcome-kinds-exhaustive": {
+        code: "FE_OUTCOME_KIND_UNHANDLED",
+        en: "A `switch` on `kind` in `<file>` has an `ok` branch but misses one of refused, invalid, not-found, unavailable.",
+        fix: "Write all five branches of `Outcome<T>`, one screen each; do not lean on `default`.",
+    },
+    "one-outcome-union": {
+        code: "FE_HTTP_STATUS_COLLAPSE",
+        en: "`<file>` declares another result union (`success`, `ok` or `kind`) outside `modules/api/graphql/types.ts`. A repo has only one result vocabulary, `GraphQLResponse<T>`.",
+        fix: "Use `GraphQLResponse<T>` of `modules/api/graphql/types.ts` (or the shared api package); put the business detail in its `data` instead of declaring a new union.",
+    },
+    "i18n-stack-in-one-module": {
+        code: "FE_I18N_PLACEMENT",
+        en: "`<file>` builds a layer of the next-intl stack itself (`defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware`). The stack is written once for the whole repo.",
+        fix: "Use the shared i18n factory; a single app keeps routing/request config in modules/i18n and navigation in modules/routes. The proxy imports routing without navigation.",
+    },
+    "no-app-relative-clock": {
+        code: "FE_SIZE_AND_STATE_BUDGET",
+        en: "`<file>` starts a recurring timer that reads the wall clock for live time labels.",
+        fix: "Render Grammar RelativeTime with the target dateTime, locale and mode; its shared ticker owns live relative time and countdown updates.",
+    },
+    "fe-stack-import": {
+        code: "FE_STACK_FORBIDDEN",
+        en: "`<file>` imports `<what>`, a package or scoped package family the front-end stack forbids, or a Supabase package outside `modules/auth`.",
+        fix: "Use the concern's canonical library from `knowledge/hfs/fe-stack.yaml` (the message names it). For @dicebear/*, pass the identity id as seed on Grammar Avatar, AvatarButton or AvatarGroup members. Supabase on the front end is the auth client in `modules/auth` only, data goes through `modules/api`.",
+    },
+    "file-size-growth": {
+        code: "HFS_SIZE_GROWTH",
+        en: "`<file>` exceeds the line budget: a new file already too long, or an existing file longer than at the parent commit. Every file must be small enough for one person to read through and one test to cover.",
+        fix: "Split the new part into its own file by responsibility; a file already over budget may only stay or shrink.",
+    },
+};

package/dist/lint-escape-hatch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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, and the three patterns below own them:
+ * ESLINT_DIRECTIVE (an ESLint switch or inline rule configuration), TS_DIRECTIVE (a TypeScript
+ * suppression) and TOOL_DIRECTIVE (Sonar's own switches, a line taken out of the coverage the gate
+ * reads, a region taken out of the formatter, 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
+ * silently ignored. `reportUnusedDisableDirectives` closes the last gap: a directive that suppresses
+ * nothing is dead weight that reads as if it did.
+ */
+import { type Recommended } from "./lib/rule.js";
+/** Inline lint configuration is repository policy, never a file-local choice. */
+export declare const noInlineLintConfig: import("./lib/rule.js").Rule<"directive" | "typescript" | "tool", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: {
+    "no-inline-lint-config": import("./lib/rule.js").Rule<"directive" | "typescript" | "tool", []>;
+};
+/** Every lint escape is a build error. */
+export declare const recommended: Recommended;

package/{lint-escape-hatch.mjs → dist/lint-escape-hatch.js}

@@ -13,12 +13,10 @@
  * silently ignored. `reportUnusedDisableDirectives` closes the last gap: a directive that suppresses
  * nothing is dead weight that reads as if it did.
  */
-
-import { isProductSource } from "./lib/scope.mjs"
-
+import { defineRule } from "./lib/rule.js";
+import { isProductSource } from "./lib/scope.js";
 /** Product source is governed; canon tests deliberately build forbidden directives. */
-const isGoverned = (context) => isProductSource(context)
-
+const isGoverned = (context) => isProductSource(context);
 /**
  * Any directive that changes ESLint's active rule set inside a source file.
  *
@@ -29,54 +27,49 @@ const isGoverned = (context) => isProductSource(context)
  * 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*:/
-
+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/
-
+const TS_DIRECTIVE = /^\s*(?:\/\s*)?@ts-(?:ignore|expect-error|nocheck)\b/;
 /**
  * A quality-tool switch other than ESLint's: Sonar honours its no-sonar word 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
-
+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;
 /** 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." },
-    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.",
-      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.",
+export const noInlineLintConfig = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "Source cannot change its own lint or type-check 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.",
+            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.",
+        },
     },
-  },
-  create(context) {
-    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" })
-        }
-      },
-    }
-  },
-}
-
+    create(context) {
+        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" });
+                }
+            },
+        };
+    },
+});
 /** The rules this law contributes to the plugin. */
 export const rules = {
-  "no-inline-lint-config": noInlineLintConfig,
-}
-
+    "no-inline-lint-config": noInlineLintConfig,
+};
 /** Every lint escape is a build error. */
 export const recommended = {
-  "starci-fe/no-inline-lint-config": "error",
-}
+    "starci-fe/no-inline-lint-config": "error",
+};

package/dist/lists.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The rules that hold `lists.md` (HFS R65 `FE_SIZE_AND_STATE_BUDGET`, sub-check `FE_LIST_KEY`).
+ *
+ * A LIST IS ITEMS WITH IDENTITY. React reconciles a rendered list by `key`: the key is how it knows
+ * that the third row is still the third row after the first was deleted. With no key React falls
+ * back to position, with an index key it says position is identity, and either way a deleted row
+ * hands its state (an open menu, a half-typed input, a focus ring) to its neighbour. Nothing fails a
+ * type check and the bug appears only on the second interaction, on a real list.
+ *
+ * WHAT COUNTS AS A LIST. A `.map` callback that returns JSX. A static array written in place
+ * (`[0, 1, 2].map(...)`) or a callback that ignores its item (`(_, index) => ...`, a skeleton) has no identity to lose, so an index key there is fine.
+ *
+ * THE MEMO TAX. A component prop written as `{{ ... }}` or `[...]` inside a `.map` callback is a new
+ * object per row per render, so `memo` on the row never hits and the whole list re-renders on every
+ * keystroke of its parent. Hoist the constant, or build it once above the map.
+ */
+import { type Recommended } from "./lib/rule.js";
+/** Every element a `.map` callback returns carries a `key`. */
+export declare const listItemHasKey: import("./lib/rule.js").Rule<"missing" | "fragment", []>;
+/** The key is never the position, and never made up on every render. */
+export declare const noIndexKey: import("./lib/rule.js").Rule<"index" | "random", []>;
+/** A component in a mapped list gets no object or array literal for a prop. */
+export declare const noInlineLiteralPropInList: import("./lib/rule.js").Rule<"literal", []>;
+/** The rules this law contributes to the plugin. */
+export declare const rules: {
+    "list-item-has-key": import("./lib/rule.js").Rule<"missing" | "fragment", []>;
+    "no-index-key": import("./lib/rule.js").Rule<"index" | "random", []>;
+    "no-inline-literal-prop-in-list": import("./lib/rule.js").Rule<"literal", []>;
+};
+/** Every rule is an error. */
+export declare const recommended: Recommended;