@figma/eslint-plugin-html-cem 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# eslint-plugin-html-cem
+
+CEM-aware HTML linting for ESLint. Validates custom-element usage in `.html` files (and HTML-in-JS template literals) against a project's [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/) (`custom-elements.json`).
+
+Built on top of [`@html-eslint/parser`](https://html-eslint.org/) — uses its AST, doesn't fork it.
+
+## Why
+
+`@html-eslint/eslint-plugin` ships rules for standard HTML5 only. It has no concept of a custom element's contract, so usages like `<my-button labl="Save" variant="ghost">` slip through. This plugin loads your CEM and adds rules that catch unknown elements, unknown attributes, missing required attributes, invalid attribute values, unknown slot names, and deprecated usage.
+
+## Install
+
+```sh
+npm i -D @figma/eslint-plugin-html-cem @html-eslint/parser
+```
+
+## Usage
+
+```js
+// eslint.config.js
+import htmlParser from "@html-eslint/parser";
+import htmlCem from "@figma/eslint-plugin-html-cem";
+
+export default [
+  {
+    files: ["**/*.html"],
+    languageOptions: { parser: htmlParser },
+    plugins: { "html-cem": htmlCem },
+    settings: {
+      "html-cem": {
+        manifests: [
+          "./custom-elements.json",
+          "./node_modules/@my-org/components/custom-elements.json",
+        ],
+      },
+    },
+    rules: {
+      ...htmlCem.configs.recommended.rules,
+    },
+  },
+];
+```
+
+## Rules
+
+| Rule | Description |
+| --- | --- |
+| [`html-cem/no-unknown-element`](docs/rules/no-unknown-element.md) | Flag dashed tags not registered in any loaded CEM. |
+| [`html-cem/no-unknown-attr`](docs/rules/no-unknown-attr.md) | Flag attributes on a known custom element that aren't in its CEM. |
+| [`html-cem/require-attrs`](docs/rules/require-attrs.md) | Flag missing attributes marked `@required` in the CEM description. |
+| [`html-cem/no-invalid-attr-value`](docs/rules/no-invalid-attr-value.md) | Validate values against CEM types (boolean / number / string-literal unions). |
+| [`html-cem/no-unknown-slot`](docs/rules/no-unknown-slot.md) | Flag `slot="x"` not declared in the parent element's CEM `slots[]`. |
+| [`html-cem/no-deprecated`](docs/rules/no-deprecated.md) | Warn on elements/attrs marked deprecated in CEM. |
+
+## Status
+
+v0 — APIs may change. Feedback welcome.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+import { ESLint, Rule } from 'eslint';
+
+interface PluginSettings {
+    manifests?: string[];
+}
+
+declare const rules: Record<string, Rule.RuleModule>;
+declare const plugin: ESLint.Plugin;
+
+export { type PluginSettings, plugin as default, rules };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { ESLint, Rule } from 'eslint';
+
+interface PluginSettings {
+    manifests?: string[];
+}
+
+declare const rules: Record<string, Rule.RuleModule>;
+declare const plugin: ESLint.Plugin;
+
+export { type PluginSettings, plugin as default, rules };

package/dist/index.js

@@ -0,0 +1,484 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  rules: () => rules
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ast/globals.ts
+var GLOBAL_HTML_ATTRS = /* @__PURE__ */ new Set([
+  "id",
+  "class",
+  "style",
+  "title",
+  "lang",
+  "dir",
+  "hidden",
+  "tabindex",
+  "accesskey",
+  "draggable",
+  "spellcheck",
+  "translate",
+  "contenteditable",
+  "autocapitalize",
+  "autofocus",
+  "inputmode",
+  "enterkeyhint",
+  "is",
+  "slot",
+  "part",
+  "exportparts",
+  "popover",
+  "role",
+  "itemid",
+  "itemprop",
+  "itemref",
+  "itemscope",
+  "itemtype",
+  "nonce"
+]);
+var GLOBAL_PREFIXES = [
+  "aria-",
+  "data-",
+  "on"
+  // event handler attrs (onclick, onfoo-bar, ...)
+];
+function isGlobalAttr(name) {
+  const lower = name.toLowerCase();
+  if (GLOBAL_HTML_ATTRS.has(lower)) return true;
+  return GLOBAL_PREFIXES.some((p) => lower.startsWith(p));
+}
+function isCustomElementName(tagName) {
+  return tagName.includes("-");
+}
+
+// src/manifest/index.ts
+var import_node_path2 = require("path");
+
+// src/manifest/load.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var fileCache = /* @__PURE__ */ new Map();
+function loadManifest(path, cwd = process.cwd()) {
+  const abs = (0, import_node_path.isAbsolute)(path) ? path : (0, import_node_path.resolve)(cwd, path);
+  const stat = (0, import_node_fs.statSync)(abs);
+  const cached = fileCache.get(abs);
+  if (cached && cached.mtimeMs === stat.mtimeMs) {
+    return cached.pkg;
+  }
+  const raw = (0, import_node_fs.readFileSync)(abs, "utf8");
+  const pkg = JSON.parse(raw);
+  fileCache.set(abs, { mtimeMs: stat.mtimeMs, pkg });
+  return pkg;
+}
+
+// src/manifest/index.ts
+var lastIndex;
+function getElementIndex(settings, cwd = process.cwd()) {
+  const manifests = settings?.manifests ?? [];
+  const resolved = manifests.map((p) => (0, import_node_path2.isAbsolute)(p) ? p : (0, import_node_path2.resolve)(cwd, p));
+  const key = resolved.join("|");
+  if (lastIndex && lastIndex.key === key) {
+    return lastIndex.index;
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const path of resolved) {
+    let pkg;
+    try {
+      pkg = loadManifest(path, cwd);
+    } catch {
+      continue;
+    }
+    indexPackage(pkg, path, index);
+  }
+  lastIndex = { key, index };
+  return index;
+}
+function indexPackage(pkg, source, index) {
+  for (const mod of pkg.modules ?? []) {
+    for (const decl of mod.declarations ?? []) {
+      if (!isCustomElementClass(decl)) continue;
+      if (!decl.tagName) continue;
+      if (index.has(decl.tagName)) continue;
+      const info = {
+        tagName: decl.tagName,
+        className: decl.name,
+        attributes: decl.attributes ?? [],
+        members: decl.members ?? [],
+        events: decl.events ?? [],
+        slots: decl.slots ?? [],
+        deprecated: decl.deprecated,
+        source
+      };
+      index.set(decl.tagName, info);
+    }
+  }
+}
+function isCustomElementClass(decl) {
+  if (!decl || typeof decl !== "object") return false;
+  const d = decl;
+  return d.kind === "class" && d.customElement === true;
+}
+
+// src/rules/no-unknown-element.ts
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow custom-element tags that are not registered in any loaded Custom Elements Manifest."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          ignore: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      unknown: "<{{tag}}> is not declared in any Custom Elements Manifest configured via settings['html-cem'].manifests."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const opts = context.options[0] ?? {};
+    const ignore = new Set(opts.ignore ?? []);
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        if (ignore.has(node.name)) return;
+        if (index.has(node.name)) return;
+        context.report({
+          node,
+          messageId: "unknown",
+          data: { tag: node.name }
+        });
+      }
+    };
+  }
+};
+var no_unknown_element_default = rule;
+
+// src/rules/no-unknown-attr.ts
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow attributes on a custom element that are not declared in its Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      unknown: "<{{tag}}> has no attribute '{{attr}}' in its Custom Elements Manifest."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const declared = new Set(info.attributes.map((a) => a.name.toLowerCase()));
+        for (const attr of node.attributes) {
+          const key = attr.key?.value;
+          if (!key) continue;
+          const lower = key.toLowerCase();
+          if (isGlobalAttr(lower)) continue;
+          if (declared.has(lower)) continue;
+          context.report({
+            node: attr.key ?? attr,
+            messageId: "unknown",
+            data: { tag: node.name, attr: key }
+          });
+        }
+      }
+    };
+  }
+};
+var no_unknown_attr_default = rule2;
+
+// src/rules/require-attrs.ts
+function isRequired(description) {
+  if (!description) return false;
+  return /(^|\s)@required(\s|$)/.test(description);
+}
+var rule3 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require attributes marked @required in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      missing: "<{{tag}}> is missing required attribute '{{attr}}'."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const present = new Set(
+          node.attributes.map((a) => a.key?.value?.toLowerCase()).filter((v) => Boolean(v))
+        );
+        for (const attr of info.attributes) {
+          if (!isRequired(attr.description)) continue;
+          if (present.has(attr.name.toLowerCase())) continue;
+          context.report({
+            node,
+            messageId: "missing",
+            data: { tag: node.name, attr: attr.name }
+          });
+        }
+      }
+    };
+  }
+};
+var require_attrs_default = rule3;
+
+// src/rules/no-invalid-attr-value.ts
+function validateAttrValue(attr, value) {
+  const text = attr.type?.text?.trim();
+  if (!text) return null;
+  const cleaned = text.split("|").map((p) => p.trim()).filter((p) => p && p !== "undefined" && p !== "null").join(" | ");
+  if (cleaned === "boolean") {
+    if (value === "" || value === attr.name || value === "true" || value === "false") {
+      return null;
+    }
+    return "boolean";
+  }
+  if (cleaned === "number") {
+    if (value.trim() !== "" && !Number.isNaN(Number(value))) return null;
+    return "number";
+  }
+  if (cleaned === "string") return null;
+  const literals = parseStringLiteralUnion(cleaned);
+  if (literals) {
+    if (literals.includes(value)) return null;
+    return literals.map((l) => `'${l}'`).join(" | ");
+  }
+  return null;
+}
+function parseStringLiteralUnion(text) {
+  const parts = text.split("|").map((p) => p.trim());
+  const out = [];
+  for (const p of parts) {
+    const m = p.match(/^['"](.*)['"]$/);
+    if (!m || m[1] === void 0) return null;
+    out.push(m[1]);
+  }
+  return out.length > 0 ? out : null;
+}
+var rule4 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Validate attribute values against types declared in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      invalid: "Value '{{value}}' for attribute '{{attr}}' on <{{tag}}> does not match expected type: {{expected}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const declared = new Map(
+          info.attributes.map((a) => [a.name.toLowerCase(), a])
+        );
+        for (const attrNode of node.attributes) {
+          const key = attrNode.key?.value;
+          if (!key) continue;
+          const decl = declared.get(key.toLowerCase());
+          if (!decl) continue;
+          const value = attrNode.value?.value ?? "";
+          const expected = validateAttrValue(decl, value);
+          if (expected === null) continue;
+          context.report({
+            node: attrNode.value ?? attrNode,
+            messageId: "invalid",
+            data: {
+              tag: node.name,
+              attr: decl.name,
+              value,
+              expected
+            }
+          });
+        }
+      }
+    };
+  }
+};
+var no_invalid_attr_value_default = rule4;
+
+// src/rules/no-unknown-slot.ts
+var rule5 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: 'Disallow `slot="name"` values that are not declared in the parent custom element\'s Custom Elements Manifest.'
+    },
+    schema: [],
+    messages: {
+      unknown: "Slot '{{slot}}' is not declared on parent <{{parent}}>. Declared slots: {{declared}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        const sc = context.sourceCode ?? context.getSourceCode();
+        const ancestors = sc.getAncestors ? sc.getAncestors(node) : [];
+        const parent = [...ancestors].reverse().find((a) => a.type === "Tag");
+        if (!parent) return;
+        if (!isCustomElementName(parent.name)) return;
+        const info = index.get(parent.name);
+        if (!info) return;
+        const slotAttr = node.attributes.find(
+          (a) => a.key?.value.toLowerCase() === "slot"
+        );
+        if (!slotAttr || !slotAttr.value) return;
+        const slotName = slotAttr.value.value;
+        const declared = info.slots.map((s) => s.name).filter(Boolean);
+        if (declared.includes(slotName)) return;
+        if (declared.length === 0) return;
+        context.report({
+          node: slotAttr.value,
+          messageId: "unknown",
+          data: {
+            slot: slotName,
+            parent: parent.name,
+            declared: declared.map((n) => `'${n}'`).join(", ")
+          }
+        });
+      }
+    };
+  }
+};
+var no_unknown_slot_default = rule5;
+
+// src/rules/no-deprecated.ts
+function deprecationMessage(deprecated) {
+  if (deprecated === void 0 || deprecated === false) return null;
+  if (deprecated === true) return "deprecated";
+  return `deprecated: ${deprecated}`;
+}
+var rule6 = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Warn on custom elements and attributes marked deprecated in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      element: "<{{tag}}> is {{detail}}.",
+      attribute: "Attribute '{{attr}}' on <{{tag}}> is {{detail}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const elemDetail = deprecationMessage(info.deprecated);
+        if (elemDetail) {
+          context.report({
+            node,
+            messageId: "element",
+            data: { tag: node.name, detail: elemDetail }
+          });
+        }
+        const declared = new Map(
+          info.attributes.map((a) => [a.name.toLowerCase(), a])
+        );
+        for (const attrNode of node.attributes) {
+          const key = attrNode.key?.value;
+          if (!key) continue;
+          const decl = declared.get(key.toLowerCase());
+          if (!decl) continue;
+          const detail = deprecationMessage(decl.deprecated);
+          if (!detail) continue;
+          context.report({
+            node: attrNode.key ?? attrNode,
+            messageId: "attribute",
+            data: { tag: node.name, attr: decl.name, detail }
+          });
+        }
+      }
+    };
+  }
+};
+var no_deprecated_default = rule6;
+
+// src/configs/recommended.ts
+var recommended = {
+  rules: {
+    "html-cem/no-unknown-element": "error",
+    "html-cem/no-unknown-attr": "error",
+    "html-cem/require-attrs": "error",
+    "html-cem/no-invalid-attr-value": "error",
+    "html-cem/no-unknown-slot": "error",
+    "html-cem/no-deprecated": "warn"
+  }
+};
+var recommended_default = recommended;
+
+// src/index.ts
+var rules = {
+  "no-unknown-element": no_unknown_element_default,
+  "no-unknown-attr": no_unknown_attr_default,
+  "require-attrs": require_attrs_default,
+  "no-invalid-attr-value": no_invalid_attr_value_default,
+  "no-unknown-slot": no_unknown_slot_default,
+  "no-deprecated": no_deprecated_default
+};
+var plugin = {
+  meta: {
+    name: "eslint-plugin-html-cem",
+    version: "0.1.0"
+  },
+  rules,
+  configs: {
+    recommended: recommended_default
+  }
+};
+var index_default = plugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  rules
+});

package/dist/index.mjs

@@ -0,0 +1,457 @@
+// src/ast/globals.ts
+var GLOBAL_HTML_ATTRS = /* @__PURE__ */ new Set([
+  "id",
+  "class",
+  "style",
+  "title",
+  "lang",
+  "dir",
+  "hidden",
+  "tabindex",
+  "accesskey",
+  "draggable",
+  "spellcheck",
+  "translate",
+  "contenteditable",
+  "autocapitalize",
+  "autofocus",
+  "inputmode",
+  "enterkeyhint",
+  "is",
+  "slot",
+  "part",
+  "exportparts",
+  "popover",
+  "role",
+  "itemid",
+  "itemprop",
+  "itemref",
+  "itemscope",
+  "itemtype",
+  "nonce"
+]);
+var GLOBAL_PREFIXES = [
+  "aria-",
+  "data-",
+  "on"
+  // event handler attrs (onclick, onfoo-bar, ...)
+];
+function isGlobalAttr(name) {
+  const lower = name.toLowerCase();
+  if (GLOBAL_HTML_ATTRS.has(lower)) return true;
+  return GLOBAL_PREFIXES.some((p) => lower.startsWith(p));
+}
+function isCustomElementName(tagName) {
+  return tagName.includes("-");
+}
+
+// src/manifest/index.ts
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+
+// src/manifest/load.ts
+import { readFileSync, statSync } from "fs";
+import { isAbsolute, resolve } from "path";
+var fileCache = /* @__PURE__ */ new Map();
+function loadManifest(path, cwd = process.cwd()) {
+  const abs = isAbsolute(path) ? path : resolve(cwd, path);
+  const stat = statSync(abs);
+  const cached = fileCache.get(abs);
+  if (cached && cached.mtimeMs === stat.mtimeMs) {
+    return cached.pkg;
+  }
+  const raw = readFileSync(abs, "utf8");
+  const pkg = JSON.parse(raw);
+  fileCache.set(abs, { mtimeMs: stat.mtimeMs, pkg });
+  return pkg;
+}
+
+// src/manifest/index.ts
+var lastIndex;
+function getElementIndex(settings, cwd = process.cwd()) {
+  const manifests = settings?.manifests ?? [];
+  const resolved = manifests.map((p) => isAbsolute2(p) ? p : resolve2(cwd, p));
+  const key = resolved.join("|");
+  if (lastIndex && lastIndex.key === key) {
+    return lastIndex.index;
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const path of resolved) {
+    let pkg;
+    try {
+      pkg = loadManifest(path, cwd);
+    } catch {
+      continue;
+    }
+    indexPackage(pkg, path, index);
+  }
+  lastIndex = { key, index };
+  return index;
+}
+function indexPackage(pkg, source, index) {
+  for (const mod of pkg.modules ?? []) {
+    for (const decl of mod.declarations ?? []) {
+      if (!isCustomElementClass(decl)) continue;
+      if (!decl.tagName) continue;
+      if (index.has(decl.tagName)) continue;
+      const info = {
+        tagName: decl.tagName,
+        className: decl.name,
+        attributes: decl.attributes ?? [],
+        members: decl.members ?? [],
+        events: decl.events ?? [],
+        slots: decl.slots ?? [],
+        deprecated: decl.deprecated,
+        source
+      };
+      index.set(decl.tagName, info);
+    }
+  }
+}
+function isCustomElementClass(decl) {
+  if (!decl || typeof decl !== "object") return false;
+  const d = decl;
+  return d.kind === "class" && d.customElement === true;
+}
+
+// src/rules/no-unknown-element.ts
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow custom-element tags that are not registered in any loaded Custom Elements Manifest."
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          ignore: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      unknown: "<{{tag}}> is not declared in any Custom Elements Manifest configured via settings['html-cem'].manifests."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const opts = context.options[0] ?? {};
+    const ignore = new Set(opts.ignore ?? []);
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        if (ignore.has(node.name)) return;
+        if (index.has(node.name)) return;
+        context.report({
+          node,
+          messageId: "unknown",
+          data: { tag: node.name }
+        });
+      }
+    };
+  }
+};
+var no_unknown_element_default = rule;
+
+// src/rules/no-unknown-attr.ts
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow attributes on a custom element that are not declared in its Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      unknown: "<{{tag}}> has no attribute '{{attr}}' in its Custom Elements Manifest."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const declared = new Set(info.attributes.map((a) => a.name.toLowerCase()));
+        for (const attr of node.attributes) {
+          const key = attr.key?.value;
+          if (!key) continue;
+          const lower = key.toLowerCase();
+          if (isGlobalAttr(lower)) continue;
+          if (declared.has(lower)) continue;
+          context.report({
+            node: attr.key ?? attr,
+            messageId: "unknown",
+            data: { tag: node.name, attr: key }
+          });
+        }
+      }
+    };
+  }
+};
+var no_unknown_attr_default = rule2;
+
+// src/rules/require-attrs.ts
+function isRequired(description) {
+  if (!description) return false;
+  return /(^|\s)@required(\s|$)/.test(description);
+}
+var rule3 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require attributes marked @required in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      missing: "<{{tag}}> is missing required attribute '{{attr}}'."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const present = new Set(
+          node.attributes.map((a) => a.key?.value?.toLowerCase()).filter((v) => Boolean(v))
+        );
+        for (const attr of info.attributes) {
+          if (!isRequired(attr.description)) continue;
+          if (present.has(attr.name.toLowerCase())) continue;
+          context.report({
+            node,
+            messageId: "missing",
+            data: { tag: node.name, attr: attr.name }
+          });
+        }
+      }
+    };
+  }
+};
+var require_attrs_default = rule3;
+
+// src/rules/no-invalid-attr-value.ts
+function validateAttrValue(attr, value) {
+  const text = attr.type?.text?.trim();
+  if (!text) return null;
+  const cleaned = text.split("|").map((p) => p.trim()).filter((p) => p && p !== "undefined" && p !== "null").join(" | ");
+  if (cleaned === "boolean") {
+    if (value === "" || value === attr.name || value === "true" || value === "false") {
+      return null;
+    }
+    return "boolean";
+  }
+  if (cleaned === "number") {
+    if (value.trim() !== "" && !Number.isNaN(Number(value))) return null;
+    return "number";
+  }
+  if (cleaned === "string") return null;
+  const literals = parseStringLiteralUnion(cleaned);
+  if (literals) {
+    if (literals.includes(value)) return null;
+    return literals.map((l) => `'${l}'`).join(" | ");
+  }
+  return null;
+}
+function parseStringLiteralUnion(text) {
+  const parts = text.split("|").map((p) => p.trim());
+  const out = [];
+  for (const p of parts) {
+    const m = p.match(/^['"](.*)['"]$/);
+    if (!m || m[1] === void 0) return null;
+    out.push(m[1]);
+  }
+  return out.length > 0 ? out : null;
+}
+var rule4 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Validate attribute values against types declared in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      invalid: "Value '{{value}}' for attribute '{{attr}}' on <{{tag}}> does not match expected type: {{expected}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const declared = new Map(
+          info.attributes.map((a) => [a.name.toLowerCase(), a])
+        );
+        for (const attrNode of node.attributes) {
+          const key = attrNode.key?.value;
+          if (!key) continue;
+          const decl = declared.get(key.toLowerCase());
+          if (!decl) continue;
+          const value = attrNode.value?.value ?? "";
+          const expected = validateAttrValue(decl, value);
+          if (expected === null) continue;
+          context.report({
+            node: attrNode.value ?? attrNode,
+            messageId: "invalid",
+            data: {
+              tag: node.name,
+              attr: decl.name,
+              value,
+              expected
+            }
+          });
+        }
+      }
+    };
+  }
+};
+var no_invalid_attr_value_default = rule4;
+
+// src/rules/no-unknown-slot.ts
+var rule5 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: 'Disallow `slot="name"` values that are not declared in the parent custom element\'s Custom Elements Manifest.'
+    },
+    schema: [],
+    messages: {
+      unknown: "Slot '{{slot}}' is not declared on parent <{{parent}}>. Declared slots: {{declared}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        const sc = context.sourceCode ?? context.getSourceCode();
+        const ancestors = sc.getAncestors ? sc.getAncestors(node) : [];
+        const parent = [...ancestors].reverse().find((a) => a.type === "Tag");
+        if (!parent) return;
+        if (!isCustomElementName(parent.name)) return;
+        const info = index.get(parent.name);
+        if (!info) return;
+        const slotAttr = node.attributes.find(
+          (a) => a.key?.value.toLowerCase() === "slot"
+        );
+        if (!slotAttr || !slotAttr.value) return;
+        const slotName = slotAttr.value.value;
+        const declared = info.slots.map((s) => s.name).filter(Boolean);
+        if (declared.includes(slotName)) return;
+        if (declared.length === 0) return;
+        context.report({
+          node: slotAttr.value,
+          messageId: "unknown",
+          data: {
+            slot: slotName,
+            parent: parent.name,
+            declared: declared.map((n) => `'${n}'`).join(", ")
+          }
+        });
+      }
+    };
+  }
+};
+var no_unknown_slot_default = rule5;
+
+// src/rules/no-deprecated.ts
+function deprecationMessage(deprecated) {
+  if (deprecated === void 0 || deprecated === false) return null;
+  if (deprecated === true) return "deprecated";
+  return `deprecated: ${deprecated}`;
+}
+var rule6 = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Warn on custom elements and attributes marked deprecated in the Custom Elements Manifest."
+    },
+    schema: [],
+    messages: {
+      element: "<{{tag}}> is {{detail}}.",
+      attribute: "Attribute '{{attr}}' on <{{tag}}> is {{detail}}."
+    }
+  },
+  create(context) {
+    const settings = context.settings["html-cem"];
+    const index = getElementIndex(settings, context.cwd);
+    return {
+      Tag(node) {
+        if (!isCustomElementName(node.name)) return;
+        const info = index.get(node.name);
+        if (!info) return;
+        const elemDetail = deprecationMessage(info.deprecated);
+        if (elemDetail) {
+          context.report({
+            node,
+            messageId: "element",
+            data: { tag: node.name, detail: elemDetail }
+          });
+        }
+        const declared = new Map(
+          info.attributes.map((a) => [a.name.toLowerCase(), a])
+        );
+        for (const attrNode of node.attributes) {
+          const key = attrNode.key?.value;
+          if (!key) continue;
+          const decl = declared.get(key.toLowerCase());
+          if (!decl) continue;
+          const detail = deprecationMessage(decl.deprecated);
+          if (!detail) continue;
+          context.report({
+            node: attrNode.key ?? attrNode,
+            messageId: "attribute",
+            data: { tag: node.name, attr: decl.name, detail }
+          });
+        }
+      }
+    };
+  }
+};
+var no_deprecated_default = rule6;
+
+// src/configs/recommended.ts
+var recommended = {
+  rules: {
+    "html-cem/no-unknown-element": "error",
+    "html-cem/no-unknown-attr": "error",
+    "html-cem/require-attrs": "error",
+    "html-cem/no-invalid-attr-value": "error",
+    "html-cem/no-unknown-slot": "error",
+    "html-cem/no-deprecated": "warn"
+  }
+};
+var recommended_default = recommended;
+
+// src/index.ts
+var rules = {
+  "no-unknown-element": no_unknown_element_default,
+  "no-unknown-attr": no_unknown_attr_default,
+  "require-attrs": require_attrs_default,
+  "no-invalid-attr-value": no_invalid_attr_value_default,
+  "no-unknown-slot": no_unknown_slot_default,
+  "no-deprecated": no_deprecated_default
+};
+var plugin = {
+  meta: {
+    name: "eslint-plugin-html-cem",
+    version: "0.1.0"
+  },
+  rules,
+  configs: {
+    recommended: recommended_default
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default,
+  rules
+};

package/docs/rules/no-deprecated.md

@@ -0,0 +1,32 @@
+# `html-cem/no-deprecated`
+
+Warn on custom elements and attributes marked `deprecated` in the Custom Elements Manifest.
+
+## Why
+
+A `deprecated` flag on an element or attribute is an explicit migration signal from the component author. Surfacing it in the linter prevents silent accumulation of legacy usage.
+
+## Rule details
+
+- If an element's CEM declaration has `deprecated: true | string`, every usage of that tag is reported.
+- If an attribute's CEM entry has `deprecated: true | string`, every usage of that attribute on the element is reported.
+- When `deprecated` is a string, the message includes it (e.g. `"use <my-button> instead"`).
+
+Default severity in the `recommended` config is `warn`.
+
+## Examples
+
+CEM marks `<my-old-thing>` and the `legacy-flag` attribute as deprecated.
+
+❌ Reported
+
+```html
+<my-old-thing></my-old-thing>
+<my-button label="Hi" legacy-flag></my-button>
+```
+
+✅ Not reported
+
+```html
+<my-button label="Hi"></my-button>
+```

package/docs/rules/no-invalid-attr-value.md

@@ -0,0 +1,41 @@
+# `html-cem/no-invalid-attr-value`
+
+Validate attribute values against the type declared in the Custom Elements Manifest.
+
+## Why
+
+If a CEM declares `variant: 'primary' | 'ghost' | 'danger'`, passing `variant="huge"` is meaningless and almost always a bug.
+
+## Supported types
+
+CEM `type.text` is a free-form string; this rule pragmatically handles the common shapes and silently allows anything else (no false positives).
+
+| `type.text` | Accepted attribute values |
+| --- | --- |
+| `string` | any |
+| `number` | any value parseable by `Number()` |
+| `boolean` | `""`, the attribute name, `"true"`, or `"false"` |
+| `'a' \| 'b' \| 'c'` (string-literal union) | only the listed literals |
+
+A trailing ` \| undefined` or ` \| null` is stripped before matching, since attributes are presence-based.
+
+## Examples
+
+CEM declares `<my-button variant: 'primary' \| 'ghost' \| 'danger', count: number, disabled: boolean>`.
+
+❌ Incorrect
+
+```html
+<my-button variant="huge"></my-button>
+<my-button count="not-a-number"></my-button>
+<my-button disabled="maybe"></my-button>
+```
+
+✅ Correct
+
+```html
+<my-button variant="primary"></my-button>
+<my-button count="42"></my-button>
+<my-button disabled></my-button>
+<my-button disabled="disabled"></my-button>
+```

package/docs/rules/no-unknown-attr.md

@@ -0,0 +1,33 @@
+# `html-cem/no-unknown-attr`
+
+Disallow attributes on a known custom element that are not declared in its Custom Elements Manifest.
+
+## Why
+
+Misspelled or invented attributes are silently ignored at runtime. The CEM is the source of truth for a component's contract.
+
+## Rule details
+
+For each tag whose name contains `-` and is present in a loaded CEM, every attribute is checked. An attribute is flagged unless:
+- It appears in the element's `attributes[]` in the CEM, OR
+- It is a global HTML attribute (`id`, `class`, `style`, `slot`, `part`, etc.), OR
+- It starts with `aria-`, `data-`, or `on`.
+
+Tags not present in any CEM are skipped — `no-unknown-element` handles those.
+
+## Examples
+
+CEM declares `my-button` with attribute `label`.
+
+❌ Incorrect
+
+```html
+<my-button labl="Save"></my-button>
+```
+
+✅ Correct
+
+```html
+<my-button label="Save"></my-button>
+<my-button label="Save" class="hero" data-id="1" aria-label="Save"></my-button>
+```

package/docs/rules/no-unknown-element.md

@@ -0,0 +1,40 @@
+# `html-cem/no-unknown-element`
+
+Disallow custom-element tags (any tag whose name contains `-`) that are not declared in any loaded Custom Elements Manifest.
+
+## Why
+
+Custom elements that aren't registered render as inert `HTMLElement`s and silently fail. Most cases are typos (`<my-buton>`) or imports that didn't ship.
+
+## Rule details
+
+A tag is flagged if:
+- Its name contains `-` (the spec requirement for custom elements), AND
+- It does not appear in any CEM listed in `settings['html-cem'].manifests`, AND
+- It is not in the `ignore` option.
+
+Standard HTML elements are never flagged.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ignore` | `string[]` | `[]` | Tag names to skip (e.g. `["color-profile"]` for SVG foreign content, or third-party elements provided at runtime). |
+
+## Examples
+
+CEM declares `my-button`.
+
+❌ Incorrect
+
+```html
+<my-buton></my-buton>
+<undefined-thing></undefined-thing>
+```
+
+✅ Correct
+
+```html
+<my-button></my-button>
+<div><span></span></div>
+```

package/docs/rules/no-unknown-slot.md

@@ -0,0 +1,35 @@
+# `html-cem/no-unknown-slot`
+
+Disallow `slot="name"` values that are not declared in the parent custom element's Custom Elements Manifest.
+
+## Why
+
+Children with unknown slot names get rendered into the default slot or nowhere at all, and the bug is invisible until QA. The CEM `slots[]` is the source of truth.
+
+## Rule details
+
+For each child element with a `slot="x"` attribute:
+- If the child's parent is a known custom element with at least one declared slot, `x` must match a declared slot name.
+- If the parent isn't a custom element, or the CEM declares no slots, the child is skipped (we can't reason about it without info).
+
+The default slot is represented in the CEM as a slot with `name: ""`.
+
+## Examples
+
+CEM declares `my-button` with slots `[{ name: "" }, { name: "icon" }]`.
+
+❌ Incorrect
+
+```html
+<my-button label="Hi">
+  <span slot="leading"></span>
+</my-button>
+```
+
+✅ Correct
+
+```html
+<my-button label="Hi">
+  <span slot="icon"></span>
+</my-button>
+```

package/docs/rules/require-attrs.md

@@ -0,0 +1,38 @@
+# `html-cem/require-attrs`
+
+Require attributes that the Custom Elements Manifest marks `@required`.
+
+## Why
+
+The CEM schema has no native `required` field. Some component libraries communicate this through a `@required` JSDoc tag, which `@cem/analyzer` preserves in the attribute's `description`. This rule reads that convention and enforces it.
+
+## Marking an attribute required
+
+In your component source:
+
+```ts
+/**
+ * @attr {string} label - Visible button text. @required
+ */
+class MyButton extends HTMLElement {}
+```
+
+After running `@cem/analyzer`, the resulting `custom-elements.json` will contain:
+
+```json
+{ "name": "label", "description": "Visible button text. @required" }
+```
+
+## Examples
+
+❌ Incorrect
+
+```html
+<my-button></my-button>
+```
+
+✅ Correct
+
+```html
+<my-button label="Save"></my-button>
+```

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@figma/eslint-plugin-html-cem",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "ESLint plugin that lints custom-element usage in HTML files against a Custom Elements Manifest (CEM).",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "html",
+    "custom-elements",
+    "web-components",
+    "custom-elements-manifest",
+    "cem"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@html-eslint/parser": ">=0.27.0",
+    "eslint": ">=9.0.0"
+  },
+  "dependencies": {
+    "custom-elements-manifest": "^2.1.0"
+  },
+  "devDependencies": {
+    "@html-eslint/eslint-plugin": "^0.27.0",
+    "@html-eslint/parser": "^0.27.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}