@starci/eslint-canon-fe 4.0.0 → 6.0.0

package/client-boundary.mjs

@@ -0,0 +1,287 @@
+/**
+ * The rule that holds `client-boundary.md` (HFS R55, `FE_CLIENT_BOUNDARY`).
+ *
+ * SERVER FIRST. A route file is a server component; `"use client"` is a cost the app pays where a
+ * reader interacts, and it is paid once, at the top of the interactive subtree, not sprinkled
+ * wherever a hook happened to be needed. The measured alternative: 155 client files in one app,
+ * a client layout that shipped a 132 KB message catalog to every page, against 3 client files in a
+ * sibling app that did the same job server-first.
+ *
+ * The directive is allowed in exactly the places the framework or the interaction requires:
+ *   - the `index.tsx` of an interactive block (or overlay), which is the connected half;
+ *   - a leaf, whose interactivity is intrinsic (a menu, a tooltip trigger);
+ *   - `error.tsx` and `global-error.tsx`, which Next requires to be client components.
+ * Everything below a client block is already on the client and needs no directive; everything
+ * above it is a server component and must not have one.
+ */
+
+import ts from "typescript"
+import { classifyImport, fileOf, isProductSource, isSpecFile, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
+import { typed } from "./lib/types.mjs"
+
+/** The route roles that are client-only by the framework's own rule: `error` and `global-error`. */
+const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error"])
+
+/** True when the program opens with the `"use client"` directive. */
+const clientDirective = (program) =>
+  program.body.find(
+    (statement) => statement.type === "ExpressionStatement" && statement.directive === "use client",
+  ) ?? null
+
+/** The layers whose files are legitimately client: a block's entry, a leaf (its interaction is intrinsic) and, in a shared package, the interactive layers (branches and leaves; a composite is presentation). */
+const isInteractionBoundary = (context) => {
+  const slot = slotOfFile(context)
+  const kind = kindOfFile(context)
+  const role = roleOfFile(context)
+  if (slot === "fe.components") return kind === "leaves" || (kind === "blocks" && role === "entry")
+  if (slot === "fe.feature") return kind === "overlays" && role === "entry"
+  if (slot === "fe.package.ui") return kind === "branches" || kind === "leaves"
+  return false
+}
+
+/** Where the directive is a legitimate boundary. */
+const isBoundary = (context) => (slotOfFile(context) === "fe.route" && FRAMEWORK_CLIENT_ROLES.has(roleOfFile(context))) || isInteractionBoundary(context)
+
+/** The slot a file fills in the route tree (its role in `fe.route`, or the page or layout owner of a feature), when it fills one. */
+const routeFill = (context) => {
+  if (slotOfFile(context) === "fe.route" && roleOfFile(context) !== null) return roleOfFile(context)
+  if (slotOfFile(context) === "fe.feature" && kindOfFile(context) === "pages") return "page owner"
+  if (slotOfFile(context) === "fe.feature" && kindOfFile(context) === "layouts") return "layout owner"
+  return null
+}
+
+/** `"use client"` only at an interaction boundary; pages and layouts stay server components. */
+export const useClientOnlyAtBoundary = {
+  meta: {
+    type: "problem",
+    docs: { description: "`\"use client\"` appears only at a block index, a leaf, or a Next error boundary." },
+    schema: [],
+    messages: {
+      slot:
+        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`.",
+      elsewhere:
+        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, or on `error.tsx`/`global-error.tsx`. Below a client block the file is already client; above one it must stay a server component.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(fileOf(context)) || isBoundary(context)) return {}
+    const slot = routeFill(context)
+    return {
+      Program(program) {
+        const directive = clientDirective(program)
+        if (!directive) return
+        if (slot) context.report({ node: directive, messageId: "slot", data: { slot } })
+        else context.report({ node: directive, messageId: "elsewhere" })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-2 -----------------------------------------------------------------------------------
+
+/** Node built-ins a browser bundle cannot carry. */
+const NODE_BUILTINS = /^(?:node:.+|fs|fs\/promises|path|os|net|tls|http|https|http2|child_process|cluster|crypto|stream|zlib|dns|worker_threads)$/
+
+/** A server API: the request-scoped Next APIs, the server half of next-intl, a Node built-in; null for anything else. */
+const serverApiReason = (source) => {
+  if (source === "next/headers") return "`next/headers`"
+  if (source === "next/server") return "`next/server`"
+  if (source === "next-intl/server") return "`next-intl/server`"
+  if (NODE_BUILTINS.test(source)) return `\`${source}\``
+  return null
+}
+
+/** A server-only source: the marker package, a server API, a server reader (role `reader` of slot `fe.modules.api`). */
+const serverOnlyReason = (context, source) => {
+  if (source === "server-only") return "`server-only`"
+  const api = serverApiReason(source)
+  if (api) return api
+  const target = classifyImport(context, source)
+  if (target?.slot === "fe.modules.api" && target.role === "reader") return `the server reader \`${source}\``
+  return null
+}
+
+/** A client component imports nothing that only exists on the server. */
+export const clientNoServerImport = {
+  meta: {
+    type: "problem",
+    docs: { description: "A `\"use client\"` file does not import `server-only`, `next/headers`, a Node built-in or a server reader." },
+    schema: [],
+    messages: {
+      server:
+        "This client component imports {{what}}, which exists only on the server. The build either fails or, worse, pulls server code and its secrets toward the browser bundle. Read the data in a server component or a server reader and pass the result down as props, or call the app client through SWR.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(fileOf(context))) return {}
+    let client = false
+    return {
+      Program(program) {
+        client = clientDirective(program) !== null
+      },
+      ImportDeclaration(node) {
+        if (!client || node.importKind === "type") return
+        const what = serverOnlyReason(context, String(node.source.value))
+        if (what) context.report({ node, messageId: "server", data: { what } })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-2b ----------------------------------------------------------------------------------
+
+/** The slots whose files are Next route files: server components by construction, so the framework decides, not a marker. */
+const ROUTE_FILE_SLOTS = new Set(["fe.route", "fe.source-root-pinned"])
+
+/** True when a statement is `import "server-only"`: an import with no bindings from the marker package. */
+const isMarkerStatement = (statement) =>
+  statement?.type === "ImportDeclaration" && statement.specifiers.length === 0 && statement.source.value === "server-only"
+
+/** True when a TypeScript source file opens with `import "server-only"`. */
+const tsFileIsMarked = (file) => {
+  const first = file.statements[0]
+  return Boolean(first) && ts.isImportDeclaration(first) && !first.importClause && ts.isStringLiteral(first.moduleSpecifier) && first.moduleSpecifier.text === "server-only"
+}
+
+/**
+ * The source file an import specifier resolves to: the checker's module symbol, so path aliases, extensions and index
+ * files resolve as the compiler resolves them. Null for a declaration file, a package or an unresolved specifier.
+ */
+const resolvedSourceFile = (context, specifier) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(specifier)
+  if (!tsNode) return null
+  const symbol = checker.getSymbolAtLocation(tsNode)
+  const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+  return declaration && ts.isSourceFile(declaration) && !declaration.isDeclarationFile ? declaration : null
+}
+
+/** A module that uses a server-only API, or imports a module that is itself server-only, opens with `import "server-only"`. */
+/** Component tiers: a component is judged by where client code reaches it, not by a marker. */
+const COMPONENT_TIERS = new Set(["components", "feature"])
+
+export const serverModuleMarksServerOnly = {
+  meta: {
+    type: "problem",
+    docs: { description: "A module importing `next/headers`, `next/server`, `next-intl/server`, a Node built-in or a server-only module starts with `import \"server-only\"`." },
+    schema: [],
+    messages: {
+      mark:
+        "This module imports {{what}}, which exists only on the server, but it does not start with `import \"server-only\"`. Without the marker nothing stops a client component from importing this module (directly or through a hook): the build then fails far from the cause, or ships server code toward the browser. Make `import \"server-only\"` the first statement of the file. Route files (`page`, `layout`, `route`, `proxy`) are server components by construction and need no marker.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(fileOf(context))) return {}
+    const slot = slotOfFile(context)
+    if (!slot || ROUTE_FILE_SLOTS.has(slot)) return {}
+    // A block or a page is a server or client COMPONENT, not a server module: whether client code reaches the server through it is
+    // the machine's multi-hop question (FE_CLIENT_REACHES_SERVER). The marker belongs to the modules that hold server work.
+    if (COMPONENT_TIERS.has(tierOfFile(context))) return {}
+    const reader = roleOfFile(context) === "reader"
+    let client = false
+    let marked = false
+    const uses = []
+    return {
+      Program(program) {
+        client = clientDirective(program) !== null
+        marked = isMarkerStatement(program.body[0])
+      },
+      "ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration"(node) {
+        if (!node.source || node.importKind === "type" || node.exportKind === "type") return
+        const onlyTypes = node.specifiers?.length > 0 && node.specifiers.every((specifier) => specifier.importKind === "type" || specifier.exportKind === "type")
+        if (onlyTypes) return
+        const specifier = String(node.source.value)
+        if (specifier === "server-only") return
+        const api = serverApiReason(specifier)
+        if (api) {
+          uses.push({ node, what: api })
+          return
+        }
+        const target = resolvedSourceFile(context, node.source)
+        if (target && tsFileIsMarked(target)) uses.push({ node, what: `\`${specifier}\` (a module that is itself server-only)` })
+      },
+      "Program:exit"() {
+        // a "use client" file that imports the server is client-no-server-import's finding, not a missing marker
+        if (client || marked) return
+        // A server reader (`read-*.ts`, role `reader` of the api slot) is server-only by its role, whatever it imports.
+        if (reader && uses.length === 0) context.report({ node: context.sourceCode.ast, messageId: "mark", data: { what: "the request (it is a server reader)" } })
+        for (const use of uses) context.report({ node: use.node, messageId: "mark", data: { what: use.what } })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-3 -----------------------------------------------------------------------------------
+
+/** Web storage exists only in the browser and only under `modules/`, which guards it. */
+const STORAGE = new Set(["localStorage", "sessionStorage"])
+
+/** Web storage is read and written only inside `modules/`. */
+export const webStorageOnlyInModules = {
+  meta: {
+    type: "problem",
+    docs: { description: "`localStorage` and `sessionStorage` are touched only inside `modules/`." },
+    schema: [],
+    messages: {
+      storage:
+        "`{{name}}` here, outside `modules/`. Storage does not exist on the server and throws in private windows and when the quota is full, so a block that reads it during render breaks server rendering and hydrates differently from the HTML it received. Put the read and write behind a hook or a module that guards both (`typeof window`, try/catch) and let the block call that.",
+    },
+  },
+  create(context) {
+    // Product source outside the module tiers (foundation modules, the other modules, the api transport), which are where storage is guarded.
+    if (!isProductSource(context) || ["foundation", "modules", "transport"].includes(tierOfFile(context))) return {}
+    return {
+      MemberExpression(node) {
+        if (node.computed || node.property.type !== "Identifier" || !STORAGE.has(node.property.name)) return
+        if (node.object.type !== "Identifier" || (node.object.name !== "window" && node.object.name !== "globalThis")) return
+        context.report({ node, messageId: "storage", data: { name: node.property.name } })
+      },
+      Identifier(node) {
+        if (!STORAGE.has(node.name)) return
+        const parent = node.parent
+        if (parent.type === "MemberExpression" && parent.property === node) return
+        if (parent.type === "Property" && parent.key === node && !parent.shorthand) return
+        if (parent.type === "TSPropertySignature" || parent.type === "TSTypeAnnotation") return
+        context.report({ node, messageId: "storage", data: { name: node.name } })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-4 -----------------------------------------------------------------------------------
+
+/** Raw HTML is set only on a `<script>`, where the framework has no other way to inline JSON-LD or the theme bootstrap. */
+export const noDangerousHtml = {
+  meta: {
+    type: "problem",
+    docs: { description: "`dangerouslySetInnerHTML` only on `<script>`; never on a visible element." },
+    schema: [],
+    messages: {
+      html:
+        "`dangerouslySetInnerHTML` on `<{{tag}}>` writes a string into the page as markup, so any text from a user, a provider or a message catalogue becomes script. Render the content as elements. The one legitimate use is a `<script>` carrying JSON-LD or the theme bootstrap, from a constant this app wrote.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "dangerouslySetInnerHTML") return
+        const opening = node.parent
+        const tag = opening.name.type === "JSXIdentifier" ? opening.name.name : "element"
+        if (tag !== "script") context.report({ node, messageId: "html", data: { tag } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "use-client-only-at-boundary": useClientOnlyAtBoundary,
+  "client-no-server-import": clientNoServerImport,
+  "server-module-marks-server-only": serverModuleMarksServerOnly,
+  "web-storage-only-in-modules": webStorageOnlyInModules,
+  "no-dangerous-html": noDangerousHtml,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/comments.mjs

@@ -1,190 +1,137 @@
-/**
- * The rules that hold `comments.md`.
- *
- * All three reach further than their names suggest, and deliberately. A language rule that read
- * only comments would leave the same sentence legal one line lower as an identifier or a diagnostic
- * string; an emoji rule that read only JSX would miss the one in a log message. So each walks
- * comments, identifiers, string literals, template chunks and JSX text alike - everywhere prose can
- * hide in a source file.
- *
- * The exceptions are paths, not judgements, and that is on purpose: a locale dictionary IS the other
- * language, and a fixture reproducing a real string has to reproduce it exactly. A judgement-based
- * exception would be argued per file forever.
- */
-
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The letters that mark the second language this source is kept free of. */
-export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/
-
-/** The endonym a language picker must be able to render in its own script. */
-const ENDONYM = /Tiếng Việt/
-
-/** A functional literal, marked with the reason it stays. */
-const OK_PRAGMA = /\bvn-ok:/
-
-/**
- * Extended pictographs, or a regional-indicator pair.
- *
- * Two tests rather than one character class, so the class stays free of joiners and combining marks
- * - a single class covering both trips the misleading-character-class rule, and a rule that has to
- * be silenced to exist is one nobody trusts.
- */
-export const hasEmoji = (text) =>
-  typeof text === "string" &&
-  (/\p{Extended_Pictographic}/u.test(text) || /[\u{1F1E6}-\u{1F1FF}]{2}/u.test(text))
-
-/**
- * Paths whose second-language text or emoji is CONTENT rather than authoring.
- *
- * Two kinds only: the locale dictionaries, which are the product's other language, and fixtures,
- * which reproduce real strings and would be testing something else if they translated them.
- */
-export const CONTENT_PATHS = [
-  /\/messages\/[a-z-]+\.json$/i,
-  /\/src\/resources\//,
-  /\/__fixtures?__\//,
-  /\/fixtures?\//,
-  /\.fixture\.(ts|tsx|js|mjs|cjs)$/i,
-  /\.test\.(ts|tsx|js|mjs|cjs)$/i,
-  /\.spec\.(ts|tsx|js|mjs|cjs)$/i,
-]
-
-/** True when a file holds content rather than authoring. */
-export const isContentFile = (filename) => {
-  const file = normalizePath(filename)
-  return CONTENT_PATHS.some((pattern) => pattern.test(file))
-}
-
-/** Walk every place prose can hide, and hand each to one check. */
-const proseVisitors = (context, report) => {
-  const source = context.sourceCode || context.getSourceCode()
-  return {
-    Program() {
-      for (const comment of source.getAllComments()) report(comment, comment.value)
-    },
-    Identifier(node) {
-      report(node, node.name)
-    },
-    Literal(node) {
-      if (typeof node.value === "string") report(node, node.value)
-    },
-    TemplateElement(node) {
-      report(node, node.value && node.value.cooked)
-    },
-    JSXText(node) {
-      report(node, node.value)
-    },
-  }
-}
-
-// -- COMMENTS-1 ------------------------------------------------------------------------------------
-
-/** Every export opens with a documentation block. */
-export const requireExportJsdoc = {
-  meta: {
-    type: "suggestion",
-    docs: { description: "Exported declarations open with a documentation block." },
-    schema: [],
-    messages: {
-      jsdoc:
-        "`{{name}}` is exported with no documentation block. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
-    },
-  },
-  create(context) {
-    const source = context.sourceCode || context.getSourceCode()
-    const hasBlock = (node) =>
-      source.getCommentsBefore(node).some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
-    const check = (node) => {
-      const declaration = node.declaration
-      if (!declaration) return
-      const kinds = ["VariableDeclaration", "TSInterfaceDeclaration", "FunctionDeclaration", "TSTypeAliasDeclaration"]
-      if (!kinds.includes(declaration.type) || hasBlock(node)) return
-      const id =
-        declaration.id || (declaration.declarations && declaration.declarations[0] && declaration.declarations[0].id)
-      context.report({ node: id || declaration, messageId: "jsdoc", data: { name: (id && id.name) || "this export" } })
-    }
-    return { ExportNamedDeclaration: check, ExportDefaultDeclaration: check }
-  },
-}
-
-// -- COMMENTS-2 · COMMENTS-3 -----------------------------------------------------------------------
-
-/** The source is English, and the exceptions are paths plus one marked pragma. */
-export const noSecondLanguageInSource = {
-  meta: {
-    type: "problem",
-    docs: { description: "Source authoring is English; locale content and marked literals are exempt." },
-    schema: [],
-    messages: {
-      second:
-        "Second-language prose in source authoring. The bar is a stranger who joins in a year and does not share the first language of whoever wrote this line - a codebase with two languages has two populations of readers, and the smaller one stops reading the parts it cannot. If this is a literal the running program matches on or emits, keep it and mark the line with `vn-ok: <reason>`.",
-    },
-  },
-  create(context) {
-    if (isContentFile(context.filename || context.getFilename())) return {}
-    const source = context.sourceCode || context.getSourceCode()
-    /*
-     * Lines carrying the pragma, gathered once.
-     *
-     * The message tells the author to "mark the LINE", and until this existed
-     * that was not true of a literal: the exemption tested the node's OWN text,
-     * which for a string is its value, so `"Học viện Mộc" // vn-ok: ...` still
-     * reported and no phrasing could satisfy it. The rule's own valid fixture
-     * only passed because its string carried no diacritics at all.
-     *
-     * A marked line exempts the node ON it and the statement BELOW it, which are
-     * the two placements the message's wording admits.
-     */
-    const marked = new Set()
-    for (const comment of source.getAllComments()) {
-      if (!OK_PRAGMA.test(comment.value)) continue
-      marked.add(comment.loc.start.line)
-      marked.add(comment.loc.end.line + 1)
-    }
-    return proseVisitors(context, (node, text) => {
-      if (!text || !SECOND_LANGUAGE_LETTER.test(text)) return
-      if (ENDONYM.test(text) || OK_PRAGMA.test(text)) return
-      if (marked.has(node.loc.start.line)) return
-      context.report({ node, messageId: "second" })
-    })
-  },
-}
-
-// -- COMMENTS-4 ------------------------------------------------------------------------------------
-
-/** No Unicode emoji in source: stable product reactions use attributed checked-in SVG artwork. */
-export const noEmojiInSource = {
-  meta: {
-    type: "problem",
-    docs: { description: "No emoji in source authoring." },
-    schema: [],
-    messages: {
-      emoji:
-        "Unicode emoji in source authoring. It renders differently on every platform, sorts unpredictably, breaks a terminal that is not expecting it, and does not mean the same thing in two countries. Generic marks belong to the icon vocabulary; product reactions use the attributed checked-in SVG artwork through the reaction leaf.",
-    },
-  },
-  create(context) {
-    if (isContentFile(context.filename || context.getFilename())) return {}
-    return proseVisitors(context, (node, text) => {
-      if (hasEmoji(text)) context.report({ node, messageId: "emoji" })
-    })
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "require-export-jsdoc": requireExportJsdoc,
-  "no-second-language-in-source": noSecondLanguageInSource,
-  "no-emoji-in-source": noEmojiInSource,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * `require-export-jsdoc` is the one a repository adopting this with history should expect a count
- * from - every undocumented export in the tree reports at once. The other two are usually already
- * at zero, because a second language in source is noticed by readers long before a rule arrives.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+/**
+ * The rules that hold `comments.md`.
+ *
+ * Both reach further than their names suggest, and deliberately. An emoji rule that read only JSX
+ * would miss the one in a log message, so it walks comments, identifiers, string literals, template
+ * chunks and JSX text alike - everywhere prose can hide in a source file.
+ *
+ * THE SECOND-LANGUAGE RULE IS GONE. It carried a `vn-ok: <reason>` pragma, an escape hatch that was
+ * used 490 times in one repository, and one escape is enough to turn a rule into a comment
+ * convention. Its job is now held by `no-hardcoded-copy` in `translation.mjs`, which has no
+ * pragma: user-facing text comes from a `next-intl` catalogue, and the catalogue is the only place
+ * a second language is content.
+ *
+ * The exceptions that remain are placements, not judgements, and that is on purpose: a locale dictionary
+ * IS the other language, and a fixture reproducing a real string has to reproduce it exactly. A
+ * judgement-based exception would be argued per file forever.
+ */
+
+import { fileOf, inSlot, isSpecFile } from "./lib/scope.mjs"
+
+/** The letters that mark the second language a source string must not carry outside a catalogue. */
+export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/
+
+/**
+ * Extended pictographs, or a regional-indicator pair.
+ *
+ * Two tests rather than one character class, so the class stays free of joiners and combining marks
+ * - a single class covering both trips the misleading-character-class rule, and a rule that has to
+ * be silenced to exist is one nobody trusts.
+ */
+export const hasEmoji = (text) =>
+  typeof text === "string" &&
+  (/\p{Extended_Pictographic}/u.test(text) || /[\u{1F1E6}-\u{1F1FF}]{2}/u.test(text))
+
+/**
+ * Files whose second-language text or emoji is CONTENT rather than authoring, decided by what the file IS.
+ *
+ * Three kinds only: the locale dictionaries (a `.json` file of an i18n slot, `fe.modules.i18n` or `fe.package.i18n`),
+ * which are the product's other language; the e2e support tree (slot `fe.e2e-support`: fixtures and support),
+ * and specs, which reproduce real strings and would be testing something else if they translated them. There is no
+ * "copy module": a `resources/` folder of strings is copy that skipped the catalogue.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {boolean} True when the linted file holds content rather than authoring.
+ */
+export const isContentFile = (context) => {
+  const file = fileOf(context)
+  return isSpecFile(file) || inSlot(context, "fe.e2e-support") || (inSlot(context, "fe.modules.i18n", "fe.package.i18n") && file.endsWith(".json"))
+}
+
+/** Walk every place prose can hide, and hand each to one check. */
+const proseVisitors = (context, report) => {
+  const source = context.sourceCode || context.getSourceCode()
+  return {
+    Program() {
+      for (const comment of source.getAllComments()) report(comment, comment.value)
+    },
+    Identifier(node) {
+      report(node, node.name)
+    },
+    Literal(node) {
+      if (typeof node.value === "string") report(node, node.value)
+    },
+    TemplateElement(node) {
+      report(node, node.value && node.value.cooked)
+    },
+    JSXText(node) {
+      report(node, node.value)
+    },
+  }
+}
+
+// -- COMMENTS-1 ------------------------------------------------------------------------------------
+
+/** Every export opens with a documentation block. */
+export const requireExportJsdoc = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Exported declarations open with a documentation block." },
+    schema: [],
+    messages: {
+      jsdoc:
+        "`{{name}}` is exported with no documentation block. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
+    },
+  },
+  create(context) {
+    const source = context.sourceCode || context.getSourceCode()
+    const hasBlock = (node) =>
+      source.getCommentsBefore(node).some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+    const check = (node) => {
+      const declaration = node.declaration
+      if (!declaration) return
+      const kinds = ["VariableDeclaration", "TSInterfaceDeclaration", "FunctionDeclaration", "TSTypeAliasDeclaration"]
+      if (!kinds.includes(declaration.type) || hasBlock(node)) return
+      const id =
+        declaration.id || (declaration.declarations && declaration.declarations[0] && declaration.declarations[0].id)
+      context.report({ node: id || declaration, messageId: "jsdoc", data: { name: (id && id.name) || "this export" } })
+    }
+    return { ExportNamedDeclaration: check, ExportDefaultDeclaration: check }
+  },
+}
+
+// -- COMMENTS-4 ------------------------------------------------------------------------------------
+
+/** No Unicode emoji in source: stable product reactions use attributed checked-in SVG artwork. */
+export const noEmojiInSource = {
+  meta: {
+    type: "problem",
+    docs: { description: "No emoji in source authoring." },
+    schema: [],
+    messages: {
+      emoji:
+        "Unicode emoji in source authoring. It renders differently on every platform, sorts unpredictably, breaks a terminal that is not expecting it, and does not mean the same thing in two countries. Generic marks belong to the icon vocabulary; product reactions use the attributed checked-in SVG artwork through the reaction leaf.",
+    },
+  },
+  create(context) {
+    if (isContentFile(context)) return {}
+    return proseVisitors(context, (node, text) => {
+      if (hasEmoji(text)) context.report({ node, messageId: "emoji" })
+    })
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "require-export-jsdoc": requireExportJsdoc,
+  "no-emoji-in-source": noEmojiInSource,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * `require-export-jsdoc` is the one a repository adopting this with history should expect a count
+ * from - every undocumented export in the tree reports at once. The other two are usually already
+ * at zero, because a second language in source is noticed by readers long before a rule arrives.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))