@grailwind/eslint-plugin 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Firmin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @grailwind/eslint-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ESLint rules for [Grailwind](https://pafirmin.github.io/grailwind/) markup in JSX and HTML.
+
+> **Beta.** Rules, their options and the `recommended` config may change between releases.
+
+```sh
+npm install --save-dev @grailwind/eslint-plugin@beta
+```
+
+It reads the tinctures, ordinaries and charges from your installed `grailwind`, so it needs
+`grailwind` 0.4.x. For typos and other class errors, see
+[Linting](https://github.com/pafirmin/grailwind#linting) in the Grailwind README.
+
+## Setup
+
+ESLint 9 or later, flat config only. `recommended` turns on every rule as an error.
+
+JSX and TSX use ESLint's own parser:
+
+```js
+// eslint.config.js
+import grailwind from "@grailwind/eslint-plugin";
+
+export default [
+  {
+    files: ["**/*.{jsx,tsx}"],
+    languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
+  },
+  grailwind.configs.recommended,
+];
+```
+
+HTML needs [`@html-eslint/parser`](https://html-eslint.org/):
+
+```js
+import grailwind from "@grailwind/eslint-plugin";
+import html from "@html-eslint/parser";
+
+export default [
+  {
+    files: ["**/*.html"],
+    languageOptions: { parser: html },
+    ...grailwind.configs.recommended,
+  },
+];
+```
+
+## Rules
+
+### `rule-of-tincture`
+
+No metal (`or`, `argent`) on metal, and no colour on colour.
+
+- An ordinary, chief or bordure is checked against the field on the same element:
+  `escutcheon or fess-argent` is metal on metal. So are engrailed and invected ones
+  (`fess-engrailed-argent`).
+- A fimbriated ordinary is checked against its fimbriation, and the fimbriation against the
+  field: `or chevron-sable fimbriated-argent` is metal on metal (Argent on Or).
+- Charges in a `charges` container are checked against the field.
+- Charges in a `charges on` container are checked against the ordinary they lie on.
+- Charges at `in-dexter-chief`, `in-chief` or `in-sinister-chief` are checked against the chief,
+  if there is one.
+
+A divided field (`per-pale-or-gules`) has no single tincture, so nothing is checked against it.
+Neither are `<img>` charges, charges with no tincture, or `bordure-*` with a non-heraldic colour.
+Counterchanged ordinaries and charges take the field's tinctures swapped, so they're skipped too.
+
+Furs count by their ground: `ermine` and `erminois` as metals, `ermines` and `pean` as colours.
+`ermine fess-argent` is metal on metal. Authorities differ, so the `furs` option changes this:
+
+```js
+"grailwind/rule-of-tincture": ["error", { furs: "ground" }]   // the default
+"grailwind/rule-of-tincture": ["error", { furs: "exempt" }]   // furs go with anything
+"grailwind/rule-of-tincture": ["error", {
+  furs: { ermine: "metal", erminois: "exempt", ermines: "colour", pean: "colour" },
+}]
+```
+
+A fur left out of the map counts by its ground.
+
+### `charges-in-container`
+
+Charges (`mullet`, `bezant`, `charge-[…]` and so on) must be direct children of a `charges`
+container.
+
+### `arrangement-needs-ordinary`
+
+`charges between` and `charges on` take their positions from the ordinary on the shield. Without
+one, other than a chief, they have nowhere to go.
+
+### `one-ordinary`
+
+An element draws one ordinary plus, optionally, a chief. With two, such as
+`fess-azure chevron-gules`, only one shows. Two chiefs are flagged too. A `charges` container
+takes one arrangement: `between`, `on`, `in-pale`, `in-fess`, `in-bend` or `in-bend-sinister`.
+Counterchanged, engrailed, invected and fur ordinaries count as ordinaries.
+
+A charge at a named point (`in-dexter-chief` and so on) is a separate group in the blazon, so it
+goes in its own `charges` container. Among other charges, it still counts towards their number
+and shifts their positions: _three mullets, in dexter chief a crescent_ in one container lays
+the mullets out as four.
+
+### `modifier-needs-target`
+
+Modifiers that would otherwise do nothing:
+
+- `chevron-counterchanged` (any `<ordinary>-counterchanged`) needs a divided field on the same
+  element, e.g. `per-pale-argent-gules`.
+- `counterchanged` on `charges`, or on a charge, needs a divided field on the shield that holds
+  the container.
+- `fimbriated-*` needs a plain tinctured ordinary. A chief, and an engrailed, invected, fur or
+  counterchanged ordinary, aren't fimbriated.
+- `counterchanged` doesn't work on a charge with a transform (`rotate-*`, `scale-*`, `skew-*`,
+  `translate-*`): the charge shows its own small copy of the field instead.
+
+## Exceptions
+
+Some real arms break the rule of tincture on purpose, e.g. Jerusalem, gold crosses on silver.
+Mark these with a disable comment and a reason:
+
+```html
+<!-- eslint-disable-next-line grailwind/rule-of-tincture -- armes à enquérir -->
+<i class="charge-[url(cross-potent.svg)] or"></i>
+```
+
+```jsx
+{
+  /* eslint-disable-next-line grailwind/rule-of-tincture -- armes à enquérir */
+}
+<i className="charge-[url(cross-potent.svg)] or" />;
+```
+
+To downgrade a rule instead, override it after `recommended`, e.g.
+`{ rules: { "grailwind/rule-of-tincture": "warn" } }`.
+
+## Limits
+
+The rules read static class strings only: `class="…"`, `className="…"`, or a template literal
+with no `${…}`. Anything dynamic, such as `clsx(…)` or a spread of props, is skipped rather than
+guessed at. So are elements inside a component (`<Shield>…</Shield>`) or an expression
+(`{items.map(…)}`), and classes with a variant (`md:gules`).
+
+Two field tinctures on one element are a conflict, which this plugin leaves to
+`better-tailwindcss/no-conflicting-classes`. It catches `or azure` and `ermine pean`, but not a
+fur with a plain tincture (`ermine gules`) or with a division (`per-pale-ermine-gules
+per-fess-or-azure`): their CSS properties differ, so it doesn't see them as conflicting
+(eslint-plugin-better-tailwindcss 4.10.0).
+
+The transform check knows Tailwind's transform utilities only. Other things that break
+`counterchanged` the same way, such as `filter`, `perspective` or `will-change: transform`,
+aren't flagged.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@grailwind/eslint-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.0",
+  "description": "ESLint rules for Grailwind heraldry markup: the rule of tincture and charge structure",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "grailwind",
+    "heraldry",
+    "tailwindcss"
+  ],
+  "author": "Paul Firmin",
+  "license": "MIT",
+  "peerDependencies": {
+    "@html-eslint/parser": "*",
+    "eslint": "^9.0.0 || ^10.0.0",
+    "grailwind": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@html-eslint/parser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@html-eslint/parser": "^0.67.0",
+    "eslint": "^10.14.0",
+    "grailwind": "file:../.."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://pafirmin.github.io/grailwind/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pafirmin/grailwind.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/pafirmin/grailwind/issues"
+  }
+}

package/src/blazon.js

@@ -0,0 +1,167 @@
+/*
+ * Reading heraldry from a set of class names.
+ */
+import {
+  ARRANGEMENTS,
+  CHARGES,
+  COLOURS,
+  DIVISIONS,
+  FURS,
+  LINES,
+  METALS,
+  ORDINARIES,
+  POINTS,
+  ROUNDELS,
+  TINCTURES,
+} from "grailwind/data";
+
+const METAL = new Set(METALS);
+const COLOUR = new Set(COLOURS);
+const FUR = new Set(Object.keys(FURS));
+// Anything a field, ordinary or charge can be painted in.
+const TINCTURE = new Set([...TINCTURES, ...FUR]);
+const CHARGE = new Set([...CHARGES, ...Object.keys(ROUNDELS)]);
+const FIMBRIATIONS = new Set(TINCTURES.map((t) => `fimbriated-${t}`));
+const CHIEF_POINTS = new Set(["in-dexter-chief", "in-chief", "in-sinister-chief"]);
+const POINT_CLASSES = new Set(Object.keys(POINTS).map((point) => `in-${point}`));
+export const ALL_ARRANGEMENTS = ["between", "on", ...ARRANGEMENTS];
+
+// Every ordinary class, e.g. `fess-or`, `fess-engrailed-ermine`, `fess-counterchanged` and
+// `bordure-or`, mapped to its parts. A counterchanged ordinary has no tincture of its own.
+const ORDINARY_CLASSES = new Map();
+for (const ordinary of ORDINARIES) {
+  for (const tincture of TINCTURE) {
+    const fur = FUR.has(tincture);
+    ORDINARY_CLASSES.set(`${ordinary}-${tincture}`, { ordinary, tincture, fur });
+    for (const line of LINES) {
+      ORDINARY_CLASSES.set(`${ordinary}-${line}-${tincture}`, { ordinary, tincture, fur, line });
+    }
+  }
+  ORDINARY_CLASSES.set(`${ordinary}-counterchanged`, {
+    ordinary,
+    tincture: null,
+    counterchanged: true,
+  });
+}
+for (const tincture of TINCTURES) {
+  ORDINARY_CLASSES.set(`bordure-${tincture}`, { ordinary: "bordure", tincture });
+}
+
+// Two furs in one division aren't generated.
+const DIVISION_CLASSES = new Set();
+for (const division of DIVISIONS) {
+  for (const a of TINCTURE) {
+    for (const b of TINCTURE) {
+      if (a !== b && !(FUR.has(a) && FUR.has(b))) {
+        DIVISION_CLASSES.add(`${division}-${a}-${b}`);
+      }
+    }
+  }
+}
+
+// Only a plain, tinctured ordinary is fimbriated (see ordinaries.js).
+export const isFimbriable = (o) => !o.counterchanged && !o.line && !o.fur;
+
+export const isFur = (tincture) => FUR.has(tincture);
+
+const groundKind = (fur) => kind(FURS[fur][0]);
+
+// What the rule's `furs` option makes of one fur: "metal", "colour" or "exempt". The rule's
+// schema has already checked the option.
+const furChoice = (fur, option) => {
+  if (option === "ground") {
+    return groundKind(fur);
+  }
+  if (option === "exempt") {
+    return "exempt";
+  }
+  // A map: a fur left out counts by its ground.
+  return option[fur] ?? groundKind(fur);
+};
+
+// Each fur's kind for kind() and sameKind(). Exempt is null, which they treat as "no check".
+export function furKinds(option = "ground") {
+  const kinds = {};
+  for (const fur of Object.keys(FURS)) {
+    const choice = furChoice(fur, option);
+    kinds[fur] = choice === "exempt" ? null : choice;
+  }
+  return kinds;
+}
+
+// `furs` is the map from furKinds().
+export const kind = (tincture, furs) => {
+  if (FUR.has(tincture)) {
+    return furs[tincture];
+  }
+  return METAL.has(tincture) ? "metal" : COLOUR.has(tincture) ? "colour" : null;
+};
+
+export const sameKind = (a, b, furs) => {
+  const k = a && b && kind(a, furs);
+  return Boolean(k) && k === kind(b, furs);
+};
+
+// The ordinaries on an element, as { cls, ordinary, tincture }, by kind.
+export function ordinariesOf(classes) {
+  const found = { ordinaries: [], chiefs: [], bordures: [] };
+  for (const cls of classes) {
+    const match = ORDINARY_CLASSES.get(cls);
+    if (!match) {
+      continue;
+    }
+    const list =
+      match.ordinary === "chief"
+        ? "chiefs"
+        : match.ordinary === "bordure"
+          ? "bordures"
+          : "ordinaries";
+    found[list].push({ cls, ...match });
+  }
+  return found;
+}
+
+export const isDivided = (classes) => [...classes].some((cls) => DIVISION_CLASSES.has(cls));
+
+// The single bare tincture of a plain field. A divided field, or none, has no tincture.
+export function fieldTincture(classes) {
+  if (isDivided(classes)) {
+    return null;
+  }
+  const tinctures = [...classes].filter((cls) => TINCTURE.has(cls));
+  return tinctures.length === 1 ? tinctures[0] : null;
+}
+
+// A charge's tincture, and the class that gives it, e.g. `bezant` → or.
+export function chargeTincture(classes) {
+  const roundel = [...classes].find((cls) => ROUNDELS[cls]);
+  if (roundel) {
+    return { cls: roundel, tincture: ROUNDELS[roundel] };
+  }
+  const tinctures = [...classes].filter((cls) => TINCTURE.has(cls));
+  return tinctures.length === 1 ? { cls: tinctures[0], tincture: tinctures[0] } : null;
+}
+
+// The element's fimbriation, e.g. `fimbriated-argent` → argent, or null.
+export function fimbriationOf(classes) {
+  const found = [...classes].filter((cls) => FIMBRIATIONS.has(cls));
+  return found.length === 1
+    ? { cls: found[0], tincture: found[0].slice("fimbriated-".length) }
+    : null;
+}
+
+export const chargeName = (classes) =>
+  [...classes].find((cls) => CHARGE.has(cls)) ??
+  ([...classes].some((cls) => cls.startsWith("charge-[")) ? "charge" : null);
+
+export const isCharge = (classes) => chargeName(classes) !== null;
+
+export const pointOf = (classes) => [...classes].find((cls) => POINT_CLASSES.has(cls));
+
+export const atChiefPoint = (classes) => [...classes].some((cls) => CHIEF_POINTS.has(cls));
+
+export const arrangementsOf = (classes) => ALL_ARRANGEMENTS.filter((name) => classes.has(name));
+
+export const titleCase = (tincture) => tincture[0].toUpperCase() + tincture.slice(1);
+
+export const describe = (name) => name.replaceAll("-", " ");

package/src/index.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import arrangementNeedsOrdinary from "./rules/arrangement-needs-ordinary.js";
+import chargesInContainer from "./rules/charges-in-container.js";
+import modifierNeedsTarget from "./rules/modifier-needs-target.js";
+import oneOrdinary from "./rules/one-ordinary.js";
+import ruleOfTincture from "./rules/rule-of-tincture.js";
+
+const { name, version } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+const plugin = {
+  meta: { name, version, namespace: "grailwind" },
+  rules: {
+    "rule-of-tincture": ruleOfTincture,
+    "charges-in-container": chargesInContainer,
+    "arrangement-needs-ordinary": arrangementNeedsOrdinary,
+    "one-ordinary": oneOrdinary,
+    "modifier-needs-target": modifierNeedsTarget,
+  },
+  configs: {},
+};
+
+plugin.configs.recommended = {
+  name: "grailwind/recommended",
+  plugins: { grailwind: plugin },
+  rules: Object.fromEntries(
+    Object.keys(plugin.rules).map((rule) => [`grailwind/${rule}`, "error"]),
+  ),
+};
+
+export default plugin;

package/src/rules/arrangement-needs-ordinary.js

@@ -0,0 +1,37 @@
+import { getElements, UNKNOWN } from "../tree.js";
+import { ordinariesOf } from "../blazon.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require an ordinary on the shield for `between` and `on`",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#arrangement-needs-ordinary",
+    },
+    schema: [],
+    messages: {
+      // A chief publishes no `between` or `on` points, so it doesn't count.
+      missing: "`{{arrangement}}` needs an ordinary other than a chief on the shield",
+    },
+  },
+
+  create(context) {
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes?.has("charges") || el.parent === UNKNOWN || !el.parent.classes) {
+            continue;
+          }
+          if (ordinariesOf(el.parent.classes).ordinaries.length) {
+            continue;
+          }
+          for (const arrangement of ["between", "on"]) {
+            if (el.classes.has(arrangement)) {
+              context.report({ node: el.reportNode, messageId: "missing", data: { arrangement } });
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/charges-in-container.js

@@ -0,0 +1,32 @@
+import { getElements, UNKNOWN } from "../tree.js";
+import { chargeName } from "../blazon.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require charges to be inside a `charges` container",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#charges-in-container",
+    },
+    schema: [],
+    messages: {
+      outside: "`{{charge}}` must be inside a `charges` container",
+    },
+  },
+
+  create(context) {
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes || el.parent === UNKNOWN || !el.parent.classes) {
+            continue;
+          }
+          const charge = chargeName(el.classes);
+          if (charge && !el.parent.classes.has("charges")) {
+            context.report({ node: el.reportNode, messageId: "outside", data: { charge } });
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/modifier-needs-target.js

@@ -0,0 +1,80 @@
+import { getElements, UNKNOWN } from "../tree.js";
+import { fimbriationOf, isDivided, isFimbriable, ordinariesOf } from "../blazon.js";
+
+// Any transform makes a charge the containing block for its fixed, swapped layer.
+const TRANSFORM = /^-?(rotate|scale|skew|translate)(-|$)/;
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow counterchanged or fimbriated classes that have nothing to apply to",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#modifier-needs-target",
+    },
+    schema: [],
+    messages: {
+      noDivision: "`{{cls}}` needs a divided field to swap, e.g. `per-pale-argent-gules`",
+      noOrdinary:
+        "`{{cls}}` needs a plain tinctured ordinary to edge: a chief, and an engrailed, invected, fur or counterchanged ordinary, aren't fimbriated",
+      transformed:
+        "`{{cls}}` breaks `counterchanged`: a transformed charge shows its own small copy of the field",
+    },
+  },
+
+  create(context) {
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes) {
+            continue;
+          }
+          const report = (node, messageId, cls) =>
+            context.report({ node, messageId, data: { cls } });
+
+          // A counterchanged ordinary's ::before inherits the swap from its own element.
+          const { ordinaries, chiefs } = ordinariesOf(el.classes);
+          if (!isDivided(el.classes)) {
+            for (const { cls } of [...ordinaries, ...chiefs].filter((o) => o.counterchanged)) {
+              report(el.reportNode, "noDivision", cls);
+            }
+          }
+
+          const fimbriation = fimbriationOf(el.classes);
+          if (fimbriation && !ordinaries.some(isFimbriable)) {
+            report(el.reportNode, "noOrdinary", fimbriation.cls);
+          }
+
+          if (el.classes.has("charges")) {
+            for (const charge of el.children) {
+              if (!charge.classes) {
+                continue;
+              }
+              const transform = [...charge.classes].find((cls) => TRANSFORM.test(cls));
+              if (
+                transform &&
+                (el.classes.has("counterchanged") || charge.classes.has("counterchanged"))
+              ) {
+                report(charge.reportNode, "transformed", transform);
+              }
+            }
+          }
+
+          // Counterchanged charges get the swap from the container's parent only.
+          if (el.classes.has("charges") && el.parent !== UNKNOWN && el.parent.classes) {
+            if (isDivided(el.parent.classes)) {
+              continue;
+            }
+            if (el.classes.has("counterchanged")) {
+              report(el.reportNode, "noDivision", "counterchanged");
+            }
+            for (const charge of el.children) {
+              if (charge.classes?.has("counterchanged")) {
+                report(charge.reportNode, "noDivision", "counterchanged");
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/one-ordinary.js

@@ -0,0 +1,69 @@
+import { getElements } from "../tree.js";
+import { arrangementsOf, ordinariesOf, pointOf } from "../blazon.js";
+
+const quote = (names) => names.map((n) => `\`${n}\``).join(" and ");
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Allow one ordinary plus a chief per element, and one arrangement per `charges` container",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#one-ordinary",
+    },
+    schema: [],
+    messages: {
+      ordinaries: "{{classes}} both draw an ordinary; only one will show.",
+      chiefs: "{{classes}} both draw a chief; only one will show",
+      arrangements: "{{classes}} both place these charges",
+      pointed:
+        "`{{cls}}` sets this charge apart from the others in its container; give it a `charges` container of its own",
+    },
+  },
+
+  create(context) {
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes) {
+            continue;
+          }
+          const { ordinaries, chiefs } = ordinariesOf(el.classes);
+          const report = (messageId, names) =>
+            context.report({ node: el.reportNode, messageId, data: { classes: quote(names) } });
+
+          if (ordinaries.length > 1) {
+            report(
+              "ordinaries",
+              ordinaries.map((o) => o.cls),
+            );
+          }
+          if (chiefs.length > 1) {
+            report(
+              "chiefs",
+              chiefs.map((o) => o.cls),
+            );
+          }
+          if (el.classes.has("charges")) {
+            const arrangements = arrangementsOf(el.classes);
+            if (arrangements.length > 1) {
+              report("arrangements", arrangements);
+            }
+            // A pointed charge still counts towards, and shifts, the others' positions.
+            const charges = el.children.filter((child) => child.classes);
+            const pointed = charges.filter((child) => pointOf(child.classes));
+            if (pointed.length && pointed.length < charges.length) {
+              for (const charge of pointed) {
+                context.report({
+                  node: charge.reportNode,
+                  messageId: "pointed",
+                  data: { cls: pointOf(charge.classes) },
+                });
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/rule-of-tincture.js

@@ -0,0 +1,152 @@
+import { FURS } from "grailwind/data";
+import { getElements } from "../tree.js";
+import {
+  atChiefPoint,
+  chargeName,
+  chargeTincture,
+  describe,
+  fieldTincture,
+  fimbriationOf,
+  furKinds,
+  isFimbriable,
+  isFur,
+  kind,
+  ordinariesOf,
+  sameKind,
+  titleCase,
+} from "../blazon.js";
+
+const article = (thing) => (/^[aeiou]/.test(thing) ? `an ${thing}` : `a ${thing}`);
+
+const KINDS = ["metal", "colour", "exempt"];
+
+// e.g. "fess engrailed", as blazoned.
+const name = ({ ordinary, line }) => describe(line ? `${ordinary} ${line}` : ordinary);
+
+// e.g. " (ermine counts as a metal)", or " (ermine and erminois count as metals)".
+const furNote = (tinctures, kind) => {
+  const furs = [...new Set(tinctures.filter(isFur))];
+  if (!furs.length) {
+    return "";
+  }
+  return furs.length === 1
+    ? ` (${furs[0]} counts as a ${kind})`
+    : ` (${furs.join(" and ")} count as ${kind}s)`;
+};
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow metal on metal and colour on colour",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#rule-of-tincture",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          furs: {
+            oneOf: [
+              { enum: ["ground", "exempt"] },
+              {
+                type: "object",
+                properties: Object.fromEntries(
+                  Object.keys(FURS).map((fur) => [fur, { enum: KINDS }]),
+                ),
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      violation:
+        "`{{cls}}` puts {{thing}} {{tincture}} on {{ground}}: {{kind}} on {{kind}}{{note}}",
+    },
+  },
+
+  create(context) {
+    const furs = furKinds(context.options[0]?.furs);
+    const check = (node, cls, thing, tincture, ground) => {
+      if (!sameKind(tincture, ground, furs)) {
+        return;
+      }
+      context.report({
+        node,
+        messageId: "violation",
+        data: {
+          cls,
+          thing: article(thing),
+          tincture: titleCase(tincture),
+          ground: titleCase(ground),
+          kind: kind(tincture, furs),
+          note: furNote([ground, tincture], kind(tincture, furs)),
+        },
+      });
+    };
+
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes) {
+            continue;
+          }
+          const field = fieldTincture(el.classes);
+          const { ordinaries, chiefs, bordures } = ordinariesOf(el.classes);
+          const fimbriation = fimbriationOf(el.classes);
+          const isFimbriated = fimbriation && ordinaries.some(isFimbriable);
+
+          if (isFimbriated) {
+            check(el.reportNode, fimbriation.cls, "fimbriation", fimbriation.tincture, field);
+          }
+
+          for (const o of ordinaries) {
+            check(
+              el.reportNode,
+              o.cls,
+              name(o),
+              o.tincture,
+              isFimbriated && isFimbriable(o) ? fimbriation.tincture : field,
+            );
+          }
+
+          // An ordinary abuts the chief rather than lying on it, so both are checked against the field.
+          for (const o of [...chiefs, ...bordures]) {
+            check(el.reportNode, o.cls, name(o), o.tincture, field);
+          }
+
+          for (const container of el.children) {
+            if (!container.classes?.has("charges")) {
+              continue;
+            }
+            for (const charge of container.children) {
+              if (!charge.classes || charge.tag === "img") {
+                continue;
+              }
+              // Counterchanged charges take the swapped field, not a tincture of their own.
+              if (charge.classes.has("counterchanged") || container.classes.has("counterchanged")) {
+                continue;
+              }
+              const found = chargeTincture(charge.classes);
+              if (!found) {
+                continue;
+              }
+
+              let ground = field;
+              if (container.classes.has("on") && ordinaries.length) {
+                ground = ordinaries[0].tincture;
+              } else if (chiefs.length && atChiefPoint(charge.classes)) {
+                ground = chiefs[0].tincture;
+              }
+
+              const thing = describe(chargeName(charge.classes) ?? "charge");
+              check(charge.reportNode, found.cls, thing, found.tincture, ground);
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/src/tree.js

@@ -0,0 +1,129 @@
+/*
+ * One element tree for JSX and HTML. `classes` is null when they can't be known statically;
+ * `parent` is UNKNOWN when the element renders somewhere this file can't see.
+ */
+
+export const UNKNOWN = Symbol("unknown parent");
+
+const cache = new WeakMap();
+
+// Variants (`md:`, `*:`) apply only sometimes, so they're ignored. `charge-[url(…)]` has a
+// colon, but no variant.
+export const parseClasses = (value) =>
+  new Set(value.split(/\s+/).filter((c) => c && (!c.includes(":") || c.startsWith("charge-["))));
+
+export function getElements(sourceCode) {
+  let elements = cache.get(sourceCode.ast);
+  if (!elements) {
+    elements = [];
+    walk(sourceCode.ast, UNKNOWN, elements, sourceCode.visitorKeys);
+    cache.set(sourceCode.ast, elements);
+  }
+  return elements;
+}
+
+function element(node, tag, attribute, classes, parent, elements) {
+  const el = { node, reportNode: attribute ?? node, tag, classes, parent, children: [] };
+  if (parent !== UNKNOWN) {
+    parent.children.push(el);
+  }
+  elements.push(el);
+  return el;
+}
+
+function walk(node, context, elements, visitorKeys) {
+  if (!node || typeof node.type !== "string") {
+    return;
+  }
+
+  switch (node.type) {
+    case "JSXElement": {
+      const { name, attributes } = node.openingElement;
+      const isComponent = name.type !== "JSXIdentifier" || /^[A-Z]/.test(name.name);
+      const attribute = attributes.find(
+        (a) =>
+          a.type === "JSXAttribute" && (a.name.name === "className" || a.name.name === "class"),
+      );
+      const hasSpread = attributes.some((a) => a.type === "JSXSpreadAttribute");
+      const classes = isComponent || hasSpread ? null : jsxClasses(attribute);
+      const el = element(
+        node,
+        isComponent ? null : name.name,
+        attribute,
+        classes,
+        context,
+        elements,
+      );
+      walkKeys(node.openingElement, UNKNOWN, elements, visitorKeys);
+      for (const child of node.children) {
+        walk(child, isComponent ? UNKNOWN : el, elements, visitorKeys);
+      }
+      return;
+    }
+    // Fragments don't render an element, so their children belong to the parent.
+    case "JSXFragment":
+      for (const child of node.children) {
+        walk(child, context, elements, visitorKeys);
+      }
+      return;
+    case "Tag": {
+      const attribute = node.attributes.find((a) => a.key?.value.toLowerCase() === "class");
+      const el = element(
+        node,
+        node.name.toLowerCase(),
+        attribute,
+        htmlClasses(attribute),
+        context,
+        elements,
+      );
+      for (const child of node.children) {
+        walk(child, el, elements, visitorKeys);
+      }
+      return;
+    }
+    default:
+      walkKeys(node, UNKNOWN, elements, visitorKeys);
+  }
+}
+
+function walkKeys(node, context, elements, visitorKeys) {
+  for (const key of visitorKeys[node.type] ?? []) {
+    const value = node[key];
+    if (Array.isArray(value)) {
+      value.forEach((child) => walk(child, context, elements, visitorKeys));
+    } else {
+      walk(value, context, elements, visitorKeys);
+    }
+  }
+}
+
+function jsxClasses(attribute) {
+  if (!attribute || attribute.value === null) {
+    return new Set();
+  }
+  let value = attribute.value;
+  if (value.type === "JSXExpressionContainer") {
+    value = value.expression;
+  }
+  if (value.type === "Literal" && typeof value.value === "string") {
+    return parseClasses(value.value);
+  }
+  if (value.type === "TemplateLiteral" && value.expressions.length === 0) {
+    return parseClasses(value.quasis[0].value.cooked);
+  }
+  return null;
+}
+
+function htmlClasses(attribute) {
+  if (!attribute) {
+    return new Set();
+  }
+  if (!attribute.value) {
+    return new Set();
+  }
+  // Template engine syntax (`{{ x }}`) makes the value dynamic.
+  if (attribute.value.parts?.some((part) => part.type !== "Part")) {
+    return null;
+  }
+  return parseClasses(attribute.value.value);
+}