@grailwind/eslint-plugin 0.1.0-beta.4 → 0.1.0-beta.5

package/README.md

@@ -13,7 +13,7 @@ npm install --save-dev @grailwind/eslint-plugin@beta
 ```
 
 It reads the tinctures, ordinaries and charges from your installed `grailwind`, so it needs
-`grailwind` 0.8.x. For typos and other class errors, see
+`grailwind` 0.9.x. For typos and other class errors, see
 [Linting](https://github.com/pafirmin/grailwind#linting) in the Grailwind README.
 
 ## Setup
@@ -57,7 +57,7 @@ export default [
 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, invected, wavy, indented, embattled and voided ones
+  `or fess-argent` is metal on metal. So are engrailed, invected, wavy, indented, embattled and voided ones
   (`fess-engrailed-argent`, `cross-voided-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).
@@ -66,26 +66,30 @@ No metal (`or`, `argent`) on metal, and no colour on colour.
 - Charges at `in-dexter-chief`, `in-chief-point` or `in-sinister-chief`, or in a
   `charges in-chief` container, are checked against the chief, if there is one.
 - A plain canton or inescutcheon, one with nothing on it, is checked against the field it lies
-  on. One with charges, an ordinary or a division counts as arms of its own and is exempt.
+  on. An inescutcheon's field is its one child. One with charges, an ordinary or a division
+  counts as arms of its own and is exempt.
 
 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.
 
-`of-the-first` is checked as the shield's first tincture, and reported if it can't be seen.
+`of-the-first` is checked as the shield's first tincture (a quarter's own, but not a canton's or
+an inescutcheon's), and reported if it can't be seen.
 
 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:
+`ermine fess-argent` is metal on metal. The vair family (`vair`, `potent`, `vairy-or-gules` and
+the like) has no single ground, so it isn't checked. 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" },
+  furs: { ermine: "metal", erminois: "exempt", ermines: "colour", pean: "colour", vair: "metal" },
 }]
 ```
 
-A fur left out of the map counts by its ground.
+A fur left out of the map counts as it does by default.
 
 ### `charges-in-container`
 
@@ -94,6 +98,17 @@ container.
 
 An arrangement (`in-chief`, `in-pale`, `between` and so on) goes on the container, not a charge.
 
+### `field-in-shield`
+
+A `heater` or `inescutcheon` is a frame round one child, the field, which carries the blazon.
+This flags a tincture, division, ordinary, chief, bordure or `fimbriated-*` on the frame, as in
+`<div class="heater azure">`, and a `charges` container directly in it, which would be taken for
+the field. It also flags `escutcheon`, which is now `heater`:
+
+```html
+<div class="heater"><div class="azure fess-or"></div></div>
+```
+
 ### `arrangement-needs-ordinary`
 
 `charges between` and `charges on` take their positions from the ordinary on the shield. Without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grailwind/eslint-plugin",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "ESLint rules for Grailwind heraldry markup: the rule of tincture and charge structure",
   "type": "module",
   "main": "./src/index.js",
@@ -26,7 +26,7 @@
   "peerDependencies": {
     "@html-eslint/parser": "*",
     "eslint": "^9.0.0 || ^10.0.0",
-    "grailwind": "^0.8.0"
+    "grailwind": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "@html-eslint/parser": {

package/src/blazon.js

@@ -4,9 +4,12 @@
 import { UNKNOWN } from "./tree.js";
 import {
   ARRANGEMENTS,
+  BORDURE_LINES,
   CHARGES,
   COLOURS,
   DIVISIONS,
+  FRAMES,
+  FUR_PATTERNS,
   FURS,
   LINES,
   lineOrdinaries,
@@ -38,7 +41,10 @@ const ORDINARY_CLASSES = new Map();
 for (const ordinary of ORDINARIES) {
   for (const tincture of PAINT) {
     const fur = FUR.has(tincture);
-    ORDINARY_CLASSES.set(`${ordinary}-${tincture}`, { ordinary, tincture, fur });
+    // `cross-potent` is the charge, not a cross of the fur potent.
+    if (!CHARGE.has(`${ordinary}-${tincture}`)) {
+      ORDINARY_CLASSES.set(`${ordinary}-${tincture}`, { ordinary, tincture, fur });
+    }
     for (const line of LINES.filter((l) => lineOrdinaries(l).includes(ordinary))) {
       ORDINARY_CLASSES.set(`${ordinary}-${line}-${tincture}`, { ordinary, tincture, fur, line });
     }
@@ -66,8 +72,17 @@ for (const ordinary of VOIDABLE) {
     voided: true,
   });
 }
-for (const tincture of [...TINCTURES, OF_THE_FIRST]) {
-  ORDINARY_CLASSES.set(`bordure-${tincture}`, { ordinary: "bordure", tincture });
+for (const tincture of PAINT) {
+  const fur = FUR.has(tincture);
+  ORDINARY_CLASSES.set(`bordure-${tincture}`, { ordinary: "bordure", tincture, fur });
+  for (const line of BORDURE_LINES) {
+    ORDINARY_CLASSES.set(`bordure-${line}-${tincture}`, {
+      ordinary: "bordure",
+      tincture,
+      fur,
+      line,
+    });
+  }
 }
 
 // Each division class, mapped to its first tincture. Two furs in one division aren't generated.
@@ -87,19 +102,19 @@ export const isFimbriable = (o) => !o.counterchanged && !o.line && !o.fur && !o.
 
 export const isFur = (tincture) => FUR.has(tincture);
 
-const groundKind = (fur) => kind(FURS[fur][0]);
+// The ermines count by their ground. The vair family has no single ground, so it's exempt.
+const byDefault = (fur) => (FUR_PATTERNS[fur] === "ermine" ? kind(FURS[fur][0]) : "exempt");
 
 // 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);
+    return byDefault(fur);
   }
   if (option === "exempt") {
     return "exempt";
   }
-  // A map: a fur left out counts by its ground.
-  return option[fur] ?? groundKind(fur);
+  return option[fur] ?? byDefault(fur);
 };
 
 // Each fur's kind for kind() and sameKind(). Exempt is null, which they treat as "no check".
@@ -146,6 +161,36 @@ export function ordinariesOf(classes) {
 
 export const isDivided = (classes) => [...classes].some((cls) => DIVISION_CLASSES.has(cls));
 
+/**
+ * The frame an element is, e.g. `heater` or `inescutcheon`, or undefined.
+ * @param {Set<string>} classes The element's classes.
+ * @returns {string|undefined} The frame's class.
+ */
+export const frameOf = (classes) => FRAMES.find((frame) => classes.has(frame));
+
+/**
+ * The classes that belong on a field: its tincture or division, its ordinaries, chief and
+ * bordure, and their fimbriation.
+ * @param {Set<string>} classes The element's classes.
+ * @returns {string[]} Those of `classes` that do.
+ */
+export const fieldClassesOf = (classes) =>
+  [...classes].filter(
+    (cls) =>
+      PAINT.has(cls) ||
+      DIVISIONS.includes(cls) ||
+      DIVISION_CLASSES.has(cls) ||
+      ORDINARY_CLASSES.has(cls) ||
+      FIMBRIATIONS.has(cls),
+  );
+
+/**
+ * A frame's field: its one child element.
+ * @param {object} el A frame, from getElements().
+ * @returns {object|null} The field, or null if the frame hasn't exactly one child element.
+ */
+export const fieldOf = (el) => (el.children.length === 1 ? el.children[0] : null);
+
 // The single bare tincture of a plain field. A divided field, or none, has no tincture.
 export function fieldTincture(classes) {
   if (isDivided(classes)) {
@@ -192,11 +237,12 @@ const fieldFirst = (classes) => {
   return division ? DIVISION_CLASSES.get(division) : fieldTincture(classes);
 };
 
-// `of-the-first` on an element: the nearest escutcheon's or quarter's first (not a canton's).
-// Null if the shield can't be seen.
+// `of-the-first` on an element: the nearest shield's or quarter's first (not a canton's, nor an
+// inescutcheon's). A shield's field is the child of its frame. Null if the shield can't be seen.
 export function firstOf(el) {
   for (let node = el; node && node !== UNKNOWN; node = node.parent) {
-    if (node.classes?.has("escutcheon") || node.parent?.classes?.has("quarterly")) {
+    const frame = node.parent?.classes && frameOf(node.parent.classes);
+    if ((frame && frame !== "inescutcheon") || node.parent?.classes?.has("quarterly")) {
       const first = fieldFirst(node.classes);
       return first === OF_THE_FIRST ? null : first;
     }

package/src/index.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import arrangementNeedsOrdinary from "./rules/arrangement-needs-ordinary.js";
 import chargesInContainer from "./rules/charges-in-container.js";
+import fieldInShield from "./rules/field-in-shield.js";
 import modifierNeedsTarget from "./rules/modifier-needs-target.js";
 import oneOrdinary from "./rules/one-ordinary.js";
 import ruleOfTincture from "./rules/rule-of-tincture.js";
@@ -17,6 +18,7 @@ const plugin = {
     "arrangement-needs-ordinary": arrangementNeedsOrdinary,
     "one-ordinary": oneOrdinary,
     "modifier-needs-target": modifierNeedsTarget,
+    "field-in-shield": fieldInShield,
   },
   configs: {},
 };

package/src/rules/field-in-shield.js

@@ -0,0 +1,45 @@
+import { getElements } from "../tree.js";
+import { fieldClassesOf, frameOf } from "../blazon.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require the blazon on a frame's one child, the field, not on the frame",
+      url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#field-in-shield",
+    },
+    schema: [],
+    messages: {
+      onFrame: "`{{cls}}` goes on the {{frame}}'s one child, the field",
+      charges: "`charges` goes in the {{frame}}'s one child, the field, not on the {{frame}}",
+      escutcheon: "`escutcheon` is now `heater`, with the blazon on its one child",
+    },
+  },
+
+  create(context) {
+    return {
+      Program() {
+        for (const el of getElements(context.sourceCode)) {
+          if (!el.classes) {
+            continue;
+          }
+          if (el.classes.has("escutcheon")) {
+            context.report({ node: el.reportNode, messageId: "escutcheon" });
+          }
+          const frame = frameOf(el.classes);
+          if (!frame) {
+            continue;
+          }
+          for (const cls of fieldClassesOf(el.classes)) {
+            context.report({ node: el.reportNode, messageId: "onFrame", data: { cls, frame } });
+          }
+          for (const child of el.children) {
+            if (child.classes?.has("charges")) {
+              context.report({ node: child.reportNode, messageId: "charges", data: { frame } });
+            }
+          }
+        }
+      },
+    };
+  },
+};

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

@@ -4,6 +4,7 @@ import {
   chargeName,
   chargeTincture,
   describe,
+  fieldOf,
   fieldTincture,
   fimbriationOf,
   firstOf,
@@ -118,11 +119,19 @@ export default {
           const { ordinaries, chiefs, bordures } = ordinariesOf(el.classes);
           const fimbriation = fimbriationOf(el.classes);
 
-          // A plain sub-shield lies on its parent's field. A charged or divided one is arms.
+          // A plain sub-shield lies on its parent's field. A charged or divided one is arms. An
+          // inescutcheon is a frame, so its field is its one child.
           const sub = ["canton", "inescutcheon"].find((c) => el.classes.has(c));
-          if (sub && isPlain(el) && el.parent !== UNKNOWN && el.parent.classes) {
+          const subField = sub && (sub === "inescutcheon" ? fieldOf(el) : el);
+          if (
+            subField?.classes &&
+            isPlain(subField) &&
+            el.parent !== UNKNOWN &&
+            el.parent.classes
+          ) {
             const ground = fieldTincture(el.parent.classes);
-            check(el, el.reportNode, field, `plain ${sub}`, field, ground, "plain");
+            const tincture = fieldTincture(subField.classes);
+            check(el, subField.reportNode, tincture, `plain ${sub}`, tincture, ground, "plain");
           }
           const isFimbriated = fimbriation && ordinaries.some(isFimbriable);
 
@@ -154,7 +163,8 @@ export default {
               if (!charge.classes || charge.tag === "img") {
                 continue;
               }
-              // Counterchanged charges take the swapped field, not a tincture of their own.
+              // Counterchanged charges take the field's tinctures (swapped, or its own on a counterchanged
+              // ordinary), not one of their own.
               if (charge.classes.has("counterchanged") || container.classes.has("counterchanged")) {
                 continue;
               }