@starci/eslint-canon-fe 4.0.0 → 5.1.2

package/naming.mjs

@@ -1,75 +1,75 @@
-/**
- * The rules that hold `naming.md`.
- *
- * Two spellings, both of which work, which is exactly why they are rules: nothing corrects the
- * second one, so a file written on a Tuesday reads differently from its neighbour and every diff
- * afterwards carries noise that has nothing to do with the change.
- *
- * Neither rule can see intent, and both are deliberately narrow because of it. NAMING-1 fires on
- * shape alone - a module-level `function` - which is exact. NAMING-2 fires on the `handle` prefix
- * alone, which catches the rename-at-the-boundary case and nothing else; a name that merely
- * describes an action is not its business.
- */
-
-/** Parents that make a function declaration module-level rather than nested. */
-const MODULE_LEVEL_PARENTS = new Set(["Program", "ExportNamedDeclaration", "ExportDefaultDeclaration"])
-
-// -- NAMING-1 --------------------------------------------------------------------------------------
-
-/** A module-level function is an arrow const, so nothing exists before the line that declares it. */
-export const preferArrowExport = {
-  meta: {
-    type: "suggestion",
-    docs: { description: "Module-level functions use an arrow const, not a `function` declaration." },
-    schema: [],
-    messages: {
-      fn: "`function {{name}}` is hoisted, so it exists before the line that declares it and the order of this file stops promising anything about what is defined when. Write `const {{name}} = (...) => {...}` - a const cannot be used before it exists, so the file reads in the order it runs.",
-    },
-  },
-  create(context) {
-    return {
-      FunctionDeclaration(node) {
-        const parent = node.parent && node.parent.type
-        if (!MODULE_LEVEL_PARENTS.has(parent)) return
-        context.report({
-          node: node.id || node,
-          messageId: "fn",
-          data: { name: (node.id && node.id.name) || "default" },
-        })
-      },
-    }
-  },
-}
-
-// -- NAMING-2 --------------------------------------------------------------------------------------
-
-/** Something a reader triggers is named `onX`, so the name survives being passed. */
+/**
+ * The rules that hold `naming.md`.
+ *
+ * Two spellings, both of which work, which is exactly why they are rules: nothing corrects the
+ * second one, so a file written on a Tuesday reads differently from its neighbour and every diff
+ * afterwards carries noise that has nothing to do with the change.
+ *
+ * Neither rule can see intent, and both are deliberately narrow because of it. NAMING-1 fires on
+ * shape alone - a module-level `function` - which is exact. NAMING-2 fires on the `handle` prefix
+ * alone, which catches the rename-at-the-boundary case and nothing else; a name that merely
+ * describes an action is not its business.
+ */
+
+/** Parents that make a function declaration module-level rather than nested. */
+const MODULE_LEVEL_PARENTS = new Set(["Program", "ExportNamedDeclaration", "ExportDefaultDeclaration"])
+
+// -- NAMING-1 --------------------------------------------------------------------------------------
+
+/** A module-level function is an arrow const, so nothing exists before the line that declares it. */
+export const preferArrowExport = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Module-level functions use an arrow const, not a `function` declaration." },
+    schema: [],
+    messages: {
+      fn: "`function {{name}}` is hoisted, so it exists before the line that declares it and the order of this file stops promising anything about what is defined when. Write `const {{name}} = (...) => {...}` - a const cannot be used before it exists, so the file reads in the order it runs.",
+    },
+  },
+  create(context) {
+    return {
+      FunctionDeclaration(node) {
+        const parent = node.parent && node.parent.type
+        if (!MODULE_LEVEL_PARENTS.has(parent)) return
+        context.report({
+          node: node.id || node,
+          messageId: "fn",
+          data: { name: (node.id && node.id.name) || "default" },
+        })
+      },
+    }
+  },
+}
+
+// -- NAMING-2 --------------------------------------------------------------------------------------
+
+/** Something a reader triggers is named `onX`, so the name survives being passed. */
 export const handlerOnPrefix = {
-  meta: {
-    type: "suggestion",
-    docs: { description: "Handlers are named `onX`, not `handleX`." },
-    schema: [],
-    messages: {
-      handle: "`{{name}}` is renamed at every boundary it crosses - the slot is `on`, the DOM attribute is `onClick`, and the props type says `on{{rest}}`. Call it `on{{rest}}` at birth and the name is the same at the declaration, at the call site and in the type.",
-    },
-  },
-  create(context) {
-    const flag = (node, name) => {
-      if (!name || !/^handle[A-Z]/.test(name)) return
-      context.report({ node, messageId: "handle", data: { name, rest: name.slice("handle".length) } })
-    }
-    return {
-      VariableDeclarator(node) {
-        if (node.id && node.id.type === "Identifier") flag(node.id, node.id.name)
-      },
-      JSXAttribute(node) {
-        if (node.name) flag(node.name, node.name.name)
-      },
-      TSPropertySignature(node) {
-        if (node.key && node.key.type === "Identifier") flag(node.key, node.key.name)
-      },
-    }
-  },
+  meta: {
+    type: "suggestion",
+    docs: { description: "Handlers are named `onX`, not `handleX`." },
+    schema: [],
+    messages: {
+      handle: "`{{name}}` is renamed at every boundary it crosses - the slot is `on`, the DOM attribute is `onClick`, and the props type says `on{{rest}}`. Call it `on{{rest}}` at birth and the name is the same at the declaration, at the call site and in the type.",
+    },
+  },
+  create(context) {
+    const flag = (node, name) => {
+      if (!name || !/^handle[A-Z]/.test(name)) return
+      context.report({ node, messageId: "handle", data: { name, rest: name.slice("handle".length) } })
+    }
+    return {
+      VariableDeclarator(node) {
+        if (node.id && node.id.type === "Identifier") flag(node.id, node.id.name)
+      },
+      JSXAttribute(node) {
+        if (node.name) flag(node.name, node.name.name)
+      },
+      TSPropertySignature(node) {
+        if (node.key && node.key.type === "Identifier") flag(node.key, node.key.name)
+      },
+    }
+  },
 }
 
 // -- machine-only identity -------------------------------------------------------------------------
@@ -99,81 +99,81 @@ export const noDirectConstAlias = {
     }
   },
 }
-
-/** The rules this law contributes to the plugin. */
-// -- NAMING-3 --------------------------------------------------------------------------------------
-
-/** Letters that exist in Vietnamese and not in English, in the forms a path can carry. */
-const SECOND_LANGUAGE_PATH = /[àáâãèéêìíòóôõùúýăđĩũơưạảấầẩẫậắằẳẵặẹẻẽếềểễệỉịọỏốồổỗộớờởỡợụủứừửữựỳỵỷỹ]/i
-
-/**
- * Second-language words spelled in ASCII, as a route or folder segment writes them.
- *
- * A path cannot carry diacritics, so `cấp phát` reaches the filesystem as `cap-phat` and every
- * accent-based check passes it. The segments below are the ones this product actually produced.
- * A list is the honest instrument here: guessing at Vietnamese-shaped ASCII would refuse `dang`
- * in `dangerous` and `cap` in `capacity`, and a rule that fires on English words is one a
- * repository turns off.
- */
-const ROMANISED = [
-  "dang-nhap", "dang-ky", "dang-xuat", "cap-phat", "khoa-hoc", "hoc-vien", "gioi-thieu",
-  "lien-he", "tai-khoan", "thanh-toan", "gio-hang", "tin-tuc", "san-pham", "bang-gia",
-  "dieu-khoan", "chinh-sach", "trang-chu", "quan-ly", "cai-dat", "ho-so",
-]
-
-/** A route segment or folder name, lowercased, from a normalized path. */
-const segmentsOf = (filename) =>
-  String(filename || "").replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean)
-
-/**
- * A path names things in one language: the one every reader of this repository shares.
- *
- * WHY A PATH AND NOT ONLY THE SOURCE. `no-second-language-in-source` reads identifiers, comments
- * and strings, and cannot see the file it is reading. So a route could be `app/cap-phat/page.tsx`
- * with every identifier inside it in English, and nothing said a word - while the URL, the import
- * specifier, the folder in every editor sidebar and the path in every stack trace stayed in a
- * language half the readers do not have.
- *
- * A ROUTE SEGMENT IS ALSO A PUBLIC NAME. It is the address a customer sees and a support ticket
- * quotes, so this is not only an authoring question: the product's own URLs stop being readable to
- * anybody outside one language.
- */
-export const noSecondLanguageInPath = {
-  meta: {
-    type: "problem",
-    docs: { description: "File and route names are written in the repository's one shared language." },
-    schema: [],
-    messages: {
-      path:
-        "`{{segment}}` names this file in a second language. A path is read by more people than the code inside it - it is the URL a customer quotes, the folder every editor shows, and the specifier every import repeats - and unlike a comment it cannot be skimmed past. Rename the segment; the words a person READS belong in the locale catalogue, never in the address.",
-    },
-  },
-  create(context) {
-    const filename = context.filename || context.getFilename()
-    const offending = segmentsOf(filename).find(
-      (segment) => SECOND_LANGUAGE_PATH.test(segment) || ROMANISED.includes(segment.replace(/[()[\]]/g, "")),
-    )
-    if (!offending) return {}
-    return {
-      Program(node) {
-        context.report({ node, messageId: "path", data: { segment: offending } })
-      },
-    }
-  },
-}
-
+
+/** The rules this law contributes to the plugin. */
+// -- NAMING-3 --------------------------------------------------------------------------------------
+
+/** Letters that exist in Vietnamese and not in English, in the forms a path can carry. */
+const SECOND_LANGUAGE_PATH = /[àáâãèéêìíòóôõùúýăđĩũơưạảấầẩẫậắằẳẵặẹẻẽếềểễệỉịọỏốồổỗộớờởỡợụủứừửữựỳỵỷỹ]/i
+
+/**
+ * Second-language words spelled in ASCII, as a route or folder segment writes them.
+ *
+ * A path cannot carry diacritics, so `cấp phát` reaches the filesystem as `cap-phat` and every
+ * accent-based check passes it. The segments below are the ones this product actually produced.
+ * A list is the honest instrument here: guessing at Vietnamese-shaped ASCII would refuse `dang`
+ * in `dangerous` and `cap` in `capacity`, and a rule that fires on English words is one a
+ * repository turns off.
+ */
+const ROMANISED = [
+  "dang-nhap", "dang-ky", "dang-xuat", "cap-phat", "khoa-hoc", "hoc-vien", "gioi-thieu",
+  "lien-he", "tai-khoan", "thanh-toan", "gio-hang", "tin-tuc", "san-pham", "bang-gia",
+  "dieu-khoan", "chinh-sach", "trang-chu", "quan-ly", "cai-dat", "ho-so",
+]
+
+/** A route segment or folder name, lowercased, from a normalized path. */
+const segmentsOf = (filename) =>
+  String(filename || "").replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean)
+
+/**
+ * A path names things in one language: the one every reader of this repository shares.
+ *
+ * WHY A PATH AND NOT ONLY THE SOURCE. `no-second-language-in-source` reads identifiers, comments
+ * and strings, and cannot see the file it is reading. So a route could be `app/cap-phat/page.tsx`
+ * with every identifier inside it in English, and nothing said a word - while the URL, the import
+ * specifier, the folder in every editor sidebar and the path in every stack trace stayed in a
+ * language half the readers do not have.
+ *
+ * A ROUTE SEGMENT IS ALSO A PUBLIC NAME. It is the address a customer sees and a support ticket
+ * quotes, so this is not only an authoring question: the product's own URLs stop being readable to
+ * anybody outside one language.
+ */
+export const noSecondLanguageInPath = {
+  meta: {
+    type: "problem",
+    docs: { description: "File and route names are written in the repository's one shared language." },
+    schema: [],
+    messages: {
+      path:
+        "`{{segment}}` names this file in a second language. A path is read by more people than the code inside it - it is the URL a customer quotes, the folder every editor shows, and the specifier every import repeats - and unlike a comment it cannot be skimmed past. Rename the segment; the words a person READS belong in the locale catalogue, never in the address.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const offending = segmentsOf(filename).find(
+      (segment) => SECOND_LANGUAGE_PATH.test(segment) || ROMANISED.includes(segment.replace(/[()[\]]/g, "")),
+    )
+    if (!offending) return {}
+    return {
+      Program(node) {
+        context.report({ node, messageId: "path", data: { segment: offending } })
+      },
+    }
+  },
+}
+
 export const rules = {
   "prefer-arrow-export": preferArrowExport,
   "handler-on-prefix": handlerOnPrefix,
   "no-second-language-in-path": noSecondLanguageInPath,
   "no-direct-const-alias": noDirectConstAlias,
 }
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * A consuming repository's `eslint.config.mjs` stays the authority on what is actually switched on.
- * Both rules here are mechanical and auto-correctable by hand in seconds, so a repository adopting
- * them with existing debt should burn the count down rather than live at `warn`.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A consuming repository's `eslint.config.mjs` stays the authority on what is actually switched on.
+ * Both rules here are mechanical and auto-correctable by hand in seconds, so a repository adopting
+ * them with existing debt should burn the count down rather than live at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/native-controls.mjs

@@ -0,0 +1,112 @@
+/**
+ * The rule that holds `native-controls.md` (HFS R62, `FE_NATIVE_FORM_CONTROL`).
+ *
+ * THE GRAMMAR OWNS THE CONTROL. A bare `<select>`, `<input>`, `<textarea>` or `<button>` in product
+ * source is a control with no focus ring, no dark value, no density, no disabled or invalid state
+ * from the design system - it looks native on one platform and is styled by hand on the next, and
+ * the hand styling is where the private colour and pixel values came from (see `brand-values`).
+ * The renderer the grammar publishes is the same element with the state the product needs.
+ *
+ * NO TIER IS EXEMPT. The grammar package itself is not linted by this canon (it is where the native
+ * element legitimately lives); everything the product owns - leaves included - renders the grammar's
+ * control. If the grammar lacks the control, the fix is to add it to the grammar, not to draw one here.
+ */
+
+import { attribute } from "./lib/ast.mjs"
+import { isSpecFile } from "./lib/scope.mjs"
+
+/** Intrinsic elements a reader operates, that the grammar renders for the product. */
+const NATIVE = new Set(["select", "input", "textarea", "button"])
+
+/** No native form control in product source. */
+export const noNativeFormControl = {
+  meta: {
+    type: "problem",
+    docs: { description: "Use the grammar's renderers; never a bare select, input, textarea or button." },
+    schema: [],
+    messages: {
+      native:
+        "A bare `<{{tag}}>`. The grammar owns this control: it brings the focus ring, disabled and invalid states, density and the dark value, and a hand-styled native element brings none of them. Use the grammar's renderer; if it does not exist yet, add it to the grammar rather than drawing one here.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier" || !NATIVE.has(node.name.name)) return
+        context.report({ node, messageId: "native", data: { tag: node.name.name } })
+      },
+    }
+  },
+}
+
+// -- NATIVE-2 --------------------------------------------------------------------------------------
+
+/** No bare `<img>`; the framework's image owns size, format, lazy loading and layout shift. */
+export const noNativeImg = {
+  meta: {
+    type: "problem",
+    docs: { description: "Use `next/image`, never a bare `<img>`." },
+    schema: [],
+    messages: {
+      img:
+        "A bare `<img>` ships the original file at its original size, reserves no space (the page jumps when it loads) and is never lazy by policy. Use `Image` from `next/image` with `width` and `height`, or `fill` and `sizes`, and an `alt` from the message catalogue.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type === "JSXIdentifier" && node.name.name === "img") context.report({ node, messageId: "img" })
+      },
+    }
+  },
+}
+
+// -- NATIVE-3 --------------------------------------------------------------------------------------
+
+/** Every `next/image` reserves its space: a size, or `fill` inside a sized parent with `sizes`. */
+export const imageHasSize = {
+  meta: {
+    type: "problem",
+    docs: { description: "`next/image` carries `width` and `height`, or `fill` with `sizes`." },
+    schema: [],
+    messages: {
+      size:
+        "This `Image` has no `width` and `height` and is not `fill`. The browser cannot reserve its space, so the page shifts when it loads and the layout score falls. Give it both dimensions, or `fill` inside a sized parent.",
+      sizes:
+        "This `Image` is `fill` with no `sizes`. Next then assumes the image is as wide as the viewport and downloads the largest variant on every screen. State the rendered width: `sizes=\"(min-width: 768px) 33vw, 100vw\"`.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    const locals = new Set()
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== "next/image") return
+        for (const specifier of node.specifiers) if (specifier.type === "ImportDefaultSpecifier") locals.add(specifier.local.name)
+      },
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier" || !locals.has(node.name.name)) return
+        // A spread may carry the size; the rule judges what it can read.
+        if (node.attributes.some((entry) => entry.type === "JSXSpreadAttribute")) return
+        const fill = attribute(node, "fill")
+        if (fill) {
+          if (!attribute(node, "sizes")) context.report({ node, messageId: "sizes" })
+          return
+        }
+        if (!attribute(node, "width") || !attribute(node, "height")) context.report({ node, messageId: "size" })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-native-form-control": noNativeFormControl,
+  "no-native-img": noNativeImg,
+  "image-has-size": imageHasSize,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))