@starci/eslint-canon-fe 1.0.0

package/icon.mjs

@@ -0,0 +1,309 @@
+/**
+ * The rules that hold `icon.md`.
+ *
+ * Both exist because of the same escape, found by hand rather than by a gate: one leaf imported a
+ * caret straight from the glyph library, at a size off both steps and a cut outside the two the
+ * icon leaf offers. Nothing reported it. The vendor rule that guards the component library names
+ * that library only, and the token rules that police the scale read SPACING utilities - gaps,
+ * insets, offsets - so a glyph size is outside every pattern they match.
+ *
+ * The lesson is worth stating where the next rule gets written: a rule that names one vendor
+ * protects one vendor, and a rule that scans one family of utilities protects that family. Neither
+ * generalises on its own, and the gap between them is exactly where a third step gets invented.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The one module allowed to name a glyph from a library. */
+const ICON_MODULE_RELATIVE = "leaves/Icon/index.tsx"
+
+/** Repeated goal / metric cells are text-led in the legacy reference. */
+const LABELLED_PROGRESS_ROW_RELATIVE = "composites/LabelledProgressRow/index.tsx"
+
+/**
+ * Package roots that ship glyphs.
+ *
+ * Matched as a PREFIX so a subpath cannot walk around it - the escape that started this was
+ * `@phosphor-icons/react/dist/ssr`, which an equality check on the package name does not see.
+ */
+const GLYPH_PACKAGES = [
+  "@phosphor-icons/",
+  "lucide-react",
+  "react-icons",
+  "@heroicons/",
+  "@tabler/icons",
+  "@fortawesome/",
+  "@mui/icons-material",
+  "@fluentui/react-icons",
+  "iconsax-react",
+  "react-feather",
+]
+
+/** Package-name signal for a glyph catalogue not yet listed explicitly. */
+const GLYPH_PACKAGE_NAME = /(?:icon|glyph|lucide|feather|tabler|fortawesome)/i
+
+/** The two Heroicon families selected by the product roles. */
+const HEROICON_PACKAGES = new Set([
+  "@heroicons/react/24/outline",
+  "@heroicons/react/16/solid",
+])
+
+/**
+ * Product reactions are attributed artwork rather than glyph-library imports.
+ *
+ * Their leaf owns this closed vocabulary and maps it to checked-in Fluent Emoji Flat SVGs under
+ * `public/reactions/`; callers pass identities, never Unicode pictographs or asset paths.
+ */
+export const REACTION_ASSET_NAMES = new Set(["like", "love", "haha", "wow", "sad", "angry"])
+
+/**
+ * ICON-11 - rank artwork is a second closed leaf, and it is the only one.
+ *
+ * A leaderboard place is not a feature, a state or an action, which is what the Heroicons map is
+ * for. It is an AWARD, and the product decided - explicitly, twice - that an award is drawn as the
+ * Fluent Emoji Flat medal for it. Heroicons ships no medal, so the choice was never between two
+ * glyph families; it was between the artwork the product asked for and no artwork at all.
+ *
+ * WHY THIS IS A NAMED EXEMPTION RATHER THAN A HOLE. It is bounded on three sides at once: one file
+ * may import the library, only from `@iconify/react`, and only these four artwork identities. A
+ * fifth medal, a second importing file, or a different vendor is still reported. That is the same
+ * shape as the reaction vocabulary above - a closed set owned by one leaf - and it is what keeps
+ * "the product asked for it" from becoming a sentence any call site can write.
+ *
+ * WHY IT IS NOT THE `public/` ROUTE THE REACTIONS TOOK. That route is better and it stays the
+ * default: checked-in SVG needs no network at render time and no vendor at all. It was not taken
+ * here because the four assets are not in the repository, and the exemption records a decision the
+ * product owner made knowing that - not a claim that this is the stronger mechanism.
+ */
+const RANK_MARK_RELATIVE = "leaves/RankMark/index.tsx"
+
+/** The one glyph package the rank leaf may name, and nothing else may. */
+const RANK_ARTWORK_PACKAGE = "@iconify/react"
+
+/** The complete rank artwork vocabulary: three places, then one trophy for everyone below. */
+export const RANK_ARTWORK_IDS = new Set([
+  "fluent-emoji-flat:1st-place-medal",
+  "fluent-emoji-flat:2nd-place-medal",
+  "fluent-emoji-flat:3rd-place-medal",
+  "fluent-emoji-flat:trophy",
+])
+
+/** True when this file is the rank leaf, which owns the place-to-artwork map. */
+const isRankMarkFile = (filename) => normalizePath(filename).endsWith(`/${RANK_MARK_RELATIVE}`)
+
+/** True for the one import the rank leaf is permitted to make. */
+const isRankArtworkImport = (filename, source) =>
+  isRankMarkFile(filename) && source === RANK_ARTWORK_PACKAGE
+
+/** True when this file is the icon leaf, which owns the meaning-to-glyph map. */
+const isIconLeafFile = (filename) => normalizePath(filename).endsWith(`/${ICON_MODULE_RELATIVE}`)
+
+/** True for the reusable repeated metric cell whose reference contains no decorative glyph. */
+const isLabelledProgressRowFile = (filename) =>
+  normalizePath(filename).endsWith(`/${LABELLED_PROGRESS_ROW_RELATIVE}`)
+
+/** Product source under `src/`; tooling and config are out of scope. */
+const isSourceFile = (filename) => normalizePath(filename).includes("/src/")
+
+/** True when an import source resolves into a glyph library, subpaths included. */
+const isGlyphImport = (source) => {
+  const value = typeof source === "string" ? source : ""
+  const isExternalPackage = value !== "" && !value.startsWith(".") && !value.startsWith("@/")
+  return GLYPH_PACKAGES.some((pkg) => value === pkg || value.startsWith(pkg)) ||
+    (isExternalPackage && GLYPH_PACKAGE_NAME.test(value))
+}
+
+/** A glyph size written as a fraction of a step, or as an arbitrary value. */
+const OFF_SCALE_GLYPH = /\bsize-(?:\d+\.\d+|\[[^\]]+\])/
+
+/** True for a `className` / `class` JSX attribute. */
+const isClassAttribute = (node) =>
+  node.type === "JSXAttribute" && node.name && (node.name.name === "className" || node.name.name === "class")
+
+/** Static string carried by a JSX attribute, or by a module constant holding a class string. */
+const staticText = (value) => {
+  if (!value) return null
+  if (value.type === "Literal" && typeof value.value === "string") return value.value
+  if (value.type === "TemplateLiteral" && value.expressions.length === 0) {
+    return value.quasis.map((quasi) => quasi.value.cooked).join(" ")
+  }
+  if (value.type === "JSXExpressionContainer") return staticText(value.expression)
+  return null
+}
+
+// -- ICON-6 ----------------------------------------------------------------------------------------
+
+/** A glyph library is named in one file, and a caller asks for a MEANING instead. */
+export const noVendorIconOutsideIconLeaf = {
+  meta: {
+    type: "problem",
+    docs: { description: "Glyph libraries are imported only by the icon leaf." },
+    schema: [],
+    messages: {
+      vendor:
+        "`{{source}}` is a glyph library, imported outside `{{leaf}}`. Reaching for it here decides three things at the call site - which library, which glyph, how big - and the next screen answers all three differently. Ask for the MEANING instead; if no meaning fits, add one to the icon leaf, which is where the answer is kept once.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isSourceFile(file) || isIconLeafFile(file)) return {}
+    return {
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (!isGlyphImport(source)) return
+        // ICON-11: the rank leaf owns award artwork the Heroicons map does not carry.
+        if (isRankArtworkImport(file, source)) return
+        context.report({ node, messageId: "vendor", data: { source, leaf: ICON_MODULE_RELATIVE } })
+      },
+    }
+  },
+}
+
+// -- ICON-7 ----------------------------------------------------------------------------------------
+
+/** The icon leaf owns the map, but that ownership does not license a second glyph vocabulary. */
+export const heroiconsIsTheGlyphVendor = {
+  meta: {
+    type: "problem",
+    docs: { description: "Only the Heroicons heading and micro families may supply product glyphs." },
+    schema: [],
+    messages: {
+      vendor:
+        "`{{source}}` is not one of StarCi's two glyph families. Heading and leading roles use `@heroicons/react/24/outline`; chip roles use `@heroicons/react/16/solid`. Map the meaning there instead. Brand marks are exact house SVGs. Product reactions use the attributed Fluent Emoji Flat SVG subset checked into `public/reactions/`, never another glyph import.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isSourceFile(file)) return {}
+    return {
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (!isGlyphImport(source) || HEROICON_PACKAGES.has(String(source))) return
+        // ICON-11: Heroicons ships no medal, so the award vocabulary has its own closed leaf.
+        if (isRankArtworkImport(file, source)) return
+        context.report({ node, messageId: "vendor", data: { source } })
+      },
+    }
+  },
+}
+
+// -- ICON-1 ----------------------------------------------------------------------------------------
+
+/** A glyph takes one of the two steps; a fraction or an arbitrary value is a third. */
+export const noOffScaleGlyphSize = {
+  meta: {
+    type: "problem",
+    docs: { description: "A glyph is sized by one of the two steps, never by a fraction or an arbitrary value." },
+    schema: [],
+    messages: {
+      offScale:
+        "`{{cls}}` is a glyph size off both steps. A third step is one nobody applies consistently - the author picks it for a reason true on their screen, and everyone after copies the nearest of three. Use the step the icon leaf offers, and if the case genuinely needs a size neither step gives, that is a change to the two steps rather than an exception here.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isSourceFile(file)) return {}
+    const scan = (node, text) => {
+      if (!text) return
+      const hit = text.match(OFF_SCALE_GLYPH)
+      if (hit) context.report({ node, messageId: "offScale", data: { cls: hit[0] } })
+    }
+    return {
+      JSXAttribute(node) {
+        if (!isClassAttribute(node)) return
+        scan(node, staticText(node.value))
+      },
+      VariableDeclarator(node) {
+        scan(node, staticText(node.init))
+      },
+    }
+  },
+}
+
+// -- ICON-10 ---------------------------------------------------------------------------------------
+
+/** A repeated metric cell does not invent a feature glyph absent from the reference. */
+export const noDecorativeIconInMetricCell = {
+  meta: {
+    type: "problem",
+    docs: { description: "Repeated metric cells stay text-led unless the reference explicitly contains an icon." },
+    schema: [],
+    messages: {
+      decorative:
+        "`LabelledProgressRow` is a repeated metric cell, not a feature entry. Its legacy reference is text-led, so an `Icon` here invents emphasis and repeats glyph meanings across the grid. Keep the label and figure; reserve tiny glyphs for generic state or action semantics actually present in the reference.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isLabelledProgressRowFile(file)) return {}
+    return {
+      JSXOpeningElement(node) {
+        if (node.name?.type === "JSXIdentifier" && node.name.name === "Icon") {
+          context.report({ node, messageId: "decorative" })
+        }
+      },
+    }
+  },
+}
+
+// -- ICON-11 ---------------------------------------------------------------------------------------
+
+/**
+ * The rank leaf's exemption is a vocabulary, not a door.
+ *
+ * ICON-11 lets exactly one file import exactly one glyph package. Without this rule that file could
+ * then name ANY artwork in that package, and the exemption would have bought the product four
+ * medals and handed back an unbounded catalogue - which is the failure the icon leaf exists to
+ * prevent, reintroduced one folder over.
+ */
+export const rankArtworkIsAClosedSet = {
+  meta: {
+    type: "problem",
+    docs: { description: "The rank leaf names only the four approved award artworks." },
+    schema: [],
+    messages: {
+      unknown:
+        "`{{id}}` is not one of the four approved rank artworks. The vocabulary is `fluent-emoji-flat:1st-place-medal`, `2nd-place-medal`, `3rd-place-medal` and `trophy` for every place below third. A fifth artwork is a product decision about what a place MEANS, so it is made in the icon law rather than in this file.",
+      outside:
+        "`{{id}}` is rank award artwork, named outside `{{leaf}}`. The place-to-artwork map is kept in one file so a second screen cannot answer the same question differently.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    // A twin test proves the map is closed, which it cannot do without naming what is in it and
+    // what is not. Same exemption, same reason, as the one the double-cast rule already carries.
+    if (!isSourceFile(file) || /\.test\.tsx?$/.test(file)) return {}
+    const inRankLeaf = isRankMarkFile(file)
+    return {
+      Literal(node) {
+        if (typeof node.value !== "string") return
+        const id = node.value
+        if (!id.startsWith("fluent-emoji-flat:")) return
+        if (!inRankLeaf) {
+          context.report({ node, messageId: "outside", data: { id, leaf: RANK_MARK_RELATIVE } })
+          return
+        }
+        if (!RANK_ARTWORK_IDS.has(id)) context.report({ node, messageId: "unknown", data: { id } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-vendor-icon-outside-icon-leaf": noVendorIconOutsideIconLeaf,
+  "heroicons-is-the-glyph-vendor": heroiconsIsTheGlyphVendor,
+  "no-off-scale-glyph-size": noOffScaleGlyphSize,
+  "no-decorative-icon-in-metric-cell": noDecorativeIconInMetricCell,
+  "rank-artwork-is-a-closed-set": rankArtworkIsAClosedSet,
+}
+
+/**
+ * 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 are exact - a package prefix and a size pattern - so neither carries the false-positive
+ * risk that would justify adopting it at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/index.mjs

@@ -0,0 +1,118 @@
+/**
+ * The front-end plugin: every law's rules, gathered once.
+ *
+ * A consuming repository imports THIS and nothing below it. Registering rules one by one in the
+ * target's own plugin file is how the two lists drift: a law gains a rule here, nobody adds it
+ * there, and the rule ships as a document. The target's `eslint.config.mjs` stays the authority on
+ * what is switched on and at what level - that is a different question from what EXISTS, and this
+ * file answers only the second.
+ *
+ * WHAT THIS FILE REFUSES TO DO. It does not rename anything. A rule's published name is part of the
+ * law that declares it, because that name is what appears in a build log, in a disable comment and
+ * in every conversation about the failure. Aliasing one here to match a target's older spelling
+ * would leave two names for one rule and no way to tell which a message came from.
+ */
+import { recommended as commentsRecommended, rules as commentsRules } from "./comments.mjs"
+import { recommended as contractRecommended, rules as contractRules } from "./contract.mjs"
+import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
+import { recommended as iconRecommended, rules as iconRules } from "./icon.mjs"
+import { recommended as landmarkRecommended, rules as landmarkRules } from "./landmark.mjs"
+import { recommended as loadingRecommended, rules as loadingRules } from "./loading.mjs"
+import {
+  audits as lintAdoptionAudits,
+  recommended as lintAdoptionRecommended,
+  rules as lintAdoptionRules,
+} from "./lint-adoption.mjs"
+import {
+  linterOptions as strictLinterOptions,
+  recommended as lintEscapeRecommended,
+  rules as lintEscapeRules,
+} from "./lint-escape-hatch.mjs"
+import { recommended as namingRecommended, rules as namingRules } from "./naming.mjs"
+import { recommended as propsRecommended, rules as propsRules } from "./props-and-slots.mjs"
+import { recommended as servedLocaleRecommended, rules as servedLocaleRules } from "./served-locale.mjs"
+import { recommended as splitRecommended, rules as splitRules } from "./the-split.mjs"
+import { recommended as tokensRecommended, rules as tokensRules } from "./tokens.mjs"
+import { recommended as translationRecommended, rules as translationRules } from "./translation.mjs"
+import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
+import { recommended as typographyRecommended, rules as typographyRules } from "./typography.mjs"
+import { recommended as vendorRecommended, rules as vendorRules } from "./vendor-boundary.mjs"
+
+/** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
+const CONTRIBUTIONS = [
+  { law: "comments", rules: commentsRules, recommended: commentsRecommended },
+  { law: "contract", rules: contractRules, recommended: contractRecommended },
+  { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
+  { law: "icon", rules: iconRules, recommended: iconRecommended },
+  { law: "landmark", rules: landmarkRules, recommended: landmarkRecommended },
+  { law: "loading", rules: loadingRules, recommended: loadingRecommended },
+  {
+    law: "lint-adoption",
+    rules: lintAdoptionRules,
+    recommended: lintAdoptionRecommended,
+    audits: lintAdoptionAudits,
+  },
+  { law: "lint-escape-hatch", rules: lintEscapeRules, recommended: lintEscapeRecommended },
+  { law: "naming", rules: namingRules, recommended: namingRecommended },
+  { law: "props-and-slots", rules: propsRules, recommended: propsRecommended },
+  { law: "served-locale", rules: servedLocaleRules, recommended: servedLocaleRecommended },
+  { law: "the-split", rules: splitRules, recommended: splitRecommended },
+  { law: "tokens", rules: tokensRules, recommended: tokensRecommended },
+  { law: "translation", rules: translationRules, recommended: translationRecommended },
+  { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
+  { law: "typography", rules: typographyRules, recommended: typographyRecommended },
+  { law: "vendor-boundary", rules: vendorRules, recommended: vendorRecommended },
+]
+
+/** Every gathered law, including repository audits that publish no AST rule. */
+export const lawOwners = CONTRIBUTIONS.map((entry) => entry.law)
+
+/** Which law declares each repository-level audit. */
+export const auditOwners = Object.fromEntries(
+  CONTRIBUTIONS.flatMap((entry) =>
+    Object.keys(entry.audits ?? {}).map((name) => [name, entry.law]),
+  ),
+)
+
+/** Repository-level audits gathered beside the plugin. */
+export const audits = Object.fromEntries(
+  CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.audits ?? {})),
+)
+
+/**
+ * Which law declares each rule.
+ *
+ * Exported because a failing rule is a question about a LAW, and the shortest path from a build log
+ * to the document that explains it is this map. It is also what the twin test walks to prove no two
+ * laws claim one name.
+ */
+export const ruleOwners = Object.fromEntries(
+  CONTRIBUTIONS.flatMap((entry) => Object.keys(entry.rules).map((name) => [name, entry.law])),
+)
+
+/** Every rule this canon publishes, keyed by its published name. */
+export const rules = Object.fromEntries(
+  CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.rules)),
+)
+
+/**
+ * The levels this canon asks for, as the plugin's own opinion.
+ *
+ * Every FE canon rule is an error. Existing debt is fixed before adoption; lowering architecture
+ * to warn teaches every later author that the boundary is optional and is not a supported rollout.
+ */
+export const recommended = Object.fromEntries(
+  CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.recommended)),
+)
+
+/** Flat-config options that make inline directives ineffective rather than merely forbidden. */
+export const linterOptions = strictLinterOptions
+
+/** The plugin object, shaped the way a flat config expects it. */
+export default {
+  meta: { name: "eslint-plugin-starci-fe" },
+  rules,
+}
+
+/** Attach this canon to a repository: one block, one branch for its layout. */
+export { starciFeConfig, LAYOUTS } from "./lint-adoption.mjs"

package/landmark.mjs

@@ -0,0 +1,242 @@
+/**
+ * Rules for the LANDMARK law - `fe/canon/patterns/landmark.md`.
+ *
+ * WHY THESE EXIST. A registry makes the failure silent. A key named `dashboard-main` records the
+ * intent exactly and renders a `div`, because the branch that draws registry nodes draws divs. An
+ * application shipped with every region correctly named and not one landmark in the document, and
+ * no gate had anything to say: a name in a key is not an element in a document.
+ *
+ * WHAT THEY HOLD, as two halves of one idea. A route layout that composes its own chrome must hand
+ * the routed children to the landmark branch; and that branch may appear only in a ROUTE file,
+ * because a second `main` is an ambiguous landmark rather than a stronger one.
+ *
+ * WHAT THEY CANNOT HOLD, stated rather than implied. A file-at-a-time rule cannot see that a layout
+ * and a page under it BOTH opened a landmark. The rules narrow the place to route files and refuse
+ * every tier below, which is where the mistake actually happens - a reading column named `*-main`
+ * drawn with the landmark branch. The remaining cross-file case is a review question, and pretending
+ * otherwise would be the rule claiming a guarantee it does not have.
+ *
+ * WHY THE `Tree` TEST IS PART OF THE FIRST RULE. Without it the rule fires on every layout that
+ * touches `children`, including the root document shell and pass-through layouts that delegate
+ * their chrome - and satisfying it there would put the second `main` in the document that the
+ * companion rule refuses. The bluntness was real, was measured, and is the reason the condition is
+ * narrower than "renders children".
+ */
+
+import { contractHostOf } from "./contract.mjs"
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** A route layout: `layout.tsx` anywhere under an `app/` router directory. */
+export const isRouteLayoutFile = (filename) => /\/app\/(?:.*\/)?layout\.tsx$/.test(normalize(filename))
+
+/**
+ * A route file: the layout OR the page of a route.
+ *
+ * WHY BOTH. The landmark belongs to the outermost file that composes the routed screen, and that is
+ * not always a layout. A route with no chrome-composing layout - a scaffold, a standalone screen -
+ * has its page as the outermost composer, and forcing the mark upward would mean inventing a layout
+ * whose only job is to wrap. That was not a hypothetical: an early version of this rule allowed only
+ * layouts, and it refused three route pages that were each the sole composer of their screen and
+ * each held exactly one `main`.
+ */
+export const isRouteFile = (filename) => /\/app\/(?:.*\/)?(?:layout|page)\.tsx$/.test(normalize(filename))
+
+/**
+ * A page tier file: either half of a surface under `components/pages/<Name>/`.
+ *
+ * WHY THE PAGE TIER OWNS THE MARK TOO, AND WHY THIS WAS NOT ALWAYS TRUE.
+ *
+ * The landmark used to be a named branch, so "the outermost file that composes the screen" and "a
+ * file under `app/`" were the same sentence — the branch was imported into the route file and that
+ * was that. Then the mark moved into the contract entry as `host: "main"`, and the two sentences
+ * came apart: the entry is rendered by whoever renders the screen's outermost frame, and LAYOUT-6
+ * says that is emphatically NOT the route file. A route names which page renders at which URL and
+ * draws nothing.
+ *
+ * Held to route files only, the two laws then refused each other. Every page moved out of `app/` to
+ * satisfy LAYOUT-6 was reported for misplacing its landmark, and the only way to satisfy both at
+ * once was to leave the page owner in the routing tree — which is the defect LAYOUT-6 exists to
+ * prevent. A rule that can only be satisfied by breaking another rule is a finding about the rule.
+ *
+ * What the guarantee actually was, and still is: ONE main per document, owned by whoever owns the
+ * whole screen. A route file and a page component are both that. A block, composite, leaf, branch,
+ * overlay or shared layout is not, and each of those still reports — which is the case this rule was
+ * written for, because a landmark added there is a SECOND main rather than a stronger one.
+ */
+export const isPageTierFile = (filename) =>
+  /\/components\/pages\/[A-Z][A-Za-z0-9]*\/(?:index|component)\.tsx$/.test(normalize(filename))
+
+/** The branches that open a landmark element. One per element, by LANDMARK-1. */
+export const LANDMARK_BRANCHES = new Set(["Main"])
+
+/** The branch that composes an ordinary registry node, and therefore marks a layout as chrome-owning. */
+const TREE_BRANCH = "Tree"
+
+/**
+ * The contract key a frame element is rendering, when it names one literally.
+ *
+ * @param node - A JSX opening element.
+ * @returns The key, or null when the element takes no literal `contract`.
+ */
+const contractKeyOf = (node) => {
+  const attribute = (node.attributes || []).find(
+    (candidate) => candidate.type === "JSXAttribute" && candidate.name && candidate.name.name === "contract",
+  )
+  const value = attribute && attribute.value
+  return value && value.type === "Literal" && typeof value.value === "string" ? value.value : null
+}
+
+/**
+ * True when this element draws a landmark.
+ *
+ * TWO SHAPES, AND THE SECOND IS THE ONE THAT LASTS. A landmark used to be a named branch, so this
+ * asked for the name. The element now belongs to the contract entry - `host: "main"` - which is
+ * why a repository can delete its `Main` branch entirely and still have exactly one main landmark:
+ * the frame reads the host from the key. Asking only for the branch name reported those repositories
+ * as having no landmark at all, which is the opposite of what they had done.
+ *
+ * @param node - A JSX opening element.
+ * @param filename - The file being linted, used to locate the contract table.
+ */
+const isLandmarkElement = (node, filename) =>
+  isLandmarkBranchElement(node) || isHostMainFrame(node, filename)
+
+/**
+ * True when this element is a landmark BRANCH, named directly.
+ *
+ * @param node - A JSX opening element.
+ */
+const isLandmarkBranchElement = (node) =>
+  node.type === "JSXOpeningElement"
+  && node.name
+  && node.name.type === "JSXIdentifier"
+  && LANDMARK_BRANCHES.has(node.name.name)
+
+/**
+ * True when this element is an ordinary frame whose CONTRACT ENTRY declares the landmark.
+ *
+ * @param node - A JSX opening element.
+ * @param filename - The file being linted, used to locate the contract table.
+ */
+const isHostMainFrame = (node, filename) => {
+  if (node.type !== "JSXOpeningElement" || !node.name || node.name.type !== "JSXIdentifier") return false
+  if (LANDMARK_BRANCHES.has(node.name.name)) return false
+  const key = contractKeyOf(node)
+  return key !== null && contractHostOf(filename, key) === "main"
+}
+
+/**
+ * True when this file is a landmark branch's own implementation.
+ *
+ * That file draws the element by hand and must: it is the one place the element is allowed to
+ * appear, exactly as `Tree` is the one place a `div` is.
+ *
+ * @param filename - The file being linted.
+ */
+const isLandmarkBranchFile = (filename) =>
+  [...LANDMARK_BRANCHES].some((name) => new RegExp(`/branches/${name}/`).test(normalize(filename)))
+
+export const rules = {
+  "routed-page-is-a-main-landmark": {
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "A route layout that composes its own chrome must wrap the routed children in the Main branch, so the page is a landmark a reader can skip to.",
+      },
+      schema: [],
+      messages: {
+        missing:
+          "This layout composes the page chrome but never marks the routed page. Wrap `children` in the `Main` branch so assistive technology can skip the navigation to reach the page - a registry key named `*-main` is a name, not a landmark.",
+      },
+    },
+    create(context) {
+      const filename = context.filename || context.getFilename()
+      if (!isRouteLayoutFile(filename)) return {}
+      let rendersChildren = false
+      let composesChrome = false
+      let usesLandmark = false
+      let firstNode = null
+      return {
+        JSXExpressionContainer(node) {
+          if (node.expression && node.expression.type === "Identifier" && node.expression.name === "children") {
+            rendersChildren = true
+            firstNode = firstNode || node
+          }
+        },
+        Identifier(node) {
+          // `children` reaches the tree through a slot callback as often as through JSX, so the
+          // bare identifier counts too - otherwise a layout escapes by handing it to a builder.
+          if (node.name === "children" && node.parent && node.parent.type !== "Property") {
+            rendersChildren = true
+            firstNode = firstNode || node
+          }
+        },
+        JSXOpeningElement(node) {
+          if (isLandmarkElement(node, filename)) usesLandmark = true
+          if (node.name && node.name.type === "JSXIdentifier" && node.name.name === TREE_BRANCH) {
+            composesChrome = true
+            firstNode = firstNode || node
+          }
+        },
+        "Program:exit"(node) {
+          if (rendersChildren && composesChrome && !usesLandmark) {
+            context.report({ node: firstNode || node, messageId: "missing" })
+          }
+        },
+      }
+    },
+  },
+
+  "main-landmark-belongs-to-a-route-file": {
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "The Main branch draws the document's one main landmark, so it belongs to the route file that composes the screen and nowhere below it.",
+      },
+      schema: [],
+      messages: {
+        misplaced:
+          "This draws the document's ONE main landmark, so it belongs to whoever owns the whole screen - the route's `layout.tsx` or `page.tsx`, or the page surface under `components/pages/<Name>/`. Used here it puts a second `main` in the document, which is an ambiguous landmark rather than a stronger one - a registry key named `*-main` inside a block or composite is a reading column, and its entry must not declare `host: \"main\"`.",
+      },
+    },
+    /*
+     * TWO SHAPES, TWO DIFFERENT SETS OF FILES THAT MAY HOLD THEM, and collapsing them was the bug.
+     *
+     * The `Main` BRANCH is a component somebody imports in order to wrap a screen. It belongs to the
+     * route file that composes that screen and nowhere below - a page reaching for it is the trap
+     * this law was written for, because the thing it wraps is a reading COLUMN and the document then
+     * has two mains.
+     *
+     * A frame whose CONTRACT ENTRY declares `host: "main"` is not that. Nobody imported a landmark;
+     * the registry says which element this key's node opens, and the frame obeys. That entry is
+     * rendered by whoever renders the screen's outermost node - and LAYOUT-6 says the route file is
+     * emphatically not it, because a route mounts a page and draws nothing. Holding both shapes to
+     * route files only made the two laws refuse each other, and the only way to satisfy both was to
+     * leave the page owner in the routing tree, which is the defect LAYOUT-6 exists to prevent.
+     */
+    create(context) {
+      const filename = context.filename || context.getFilename()
+      if (isLandmarkBranchFile(filename)) return {}
+      const isRoute = isRouteFile(filename)
+      const isPageTier = isPageTierFile(filename)
+      return {
+        JSXOpeningElement(node) {
+          if (isLandmarkBranchElement(node)) {
+            if (!isRoute) context.report({ node, messageId: "misplaced" })
+            return
+          }
+          if (isHostMainFrame(node, filename) && !isRoute && !isPageTier) {
+            context.report({ node, messageId: "misplaced" })
+          }
+        },
+      }
+    },
+  },
+}
+
+/** Every FE canon rule is an error; see `sources/fe/index.mjs` for why there is no warn tier. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))