@esphome/compose-eslint 0.0.1 → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { ESLint, Linter } from 'eslint';
+
+/**
+ * ESPHome TSX ESLint Plugin
+ *
+ * This package provides custom ESLint rules for enforcing
+ * best practices and constraints in ESPHome TSX projects.
+ */
+
+interface ComposeESLint {
+    plugin: ESLint.Plugin;
+    recommended: Linter.Config[];
+}
+declare const composeESLint: ComposeESLint;
+
+export { type ComposeESLint, composeESLint as default };

package/dist/index.mjs

@@ -0,0 +1,226 @@
+// src/index.ts
+import tseslint from "typescript-eslint";
+
+// src/rules/jsx-children-intents.ts
+import { ESLintUtils } from "@typescript-eslint/utils";
+
+// src/utils/intent-resolver.ts
+import { INTRINSIC_INTENT_REGISTRY } from "@esphome/compose";
+function getJSXTagName(node) {
+  if (node.name.type === "JSXIdentifier") {
+    return node.name.name;
+  }
+  if (node.name.type === "JSXMemberExpression") {
+    return flattenMemberExpression(node.name);
+  }
+  return `${node.name.namespace.name}:${node.name.name.name}`;
+}
+function flattenMemberExpression(node) {
+  if (node.object.type === "JSXMemberExpression") {
+    return `${flattenMemberExpression(node.object)}.${node.property.name}`;
+  }
+  return `${node.object.name}.${node.property.name}`;
+}
+function isIntrinsicElement(tagName) {
+  const firstChar = tagName[0];
+  return firstChar === firstChar.toLowerCase() && firstChar !== firstChar.toUpperCase();
+}
+function resolveIntrinsicIntents(tagName) {
+  const meta = INTRINSIC_INTENT_REGISTRY[tagName];
+  if (!meta) return void 0;
+  return {
+    intents: meta.intents,
+    allowedChildIntents: meta.allowedChildIntents,
+    context: meta.context,
+    contextTransparent: meta.contextTransparent ?? false
+  };
+}
+function resolveElementIntents(openingElement, componentIntentCache) {
+  const tagName = getJSXTagName(openingElement);
+  if (isIntrinsicElement(tagName)) {
+    return resolveIntrinsicIntents(tagName);
+  }
+  const cached = componentIntentCache.get(tagName);
+  if (cached !== void 0) {
+    return cached ?? void 0;
+  }
+  return void 0;
+}
+function findConstrainingParent(ancestors, componentIntentCache) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const ancestor = ancestors[i];
+    if (ancestor.type !== "JSXElement") continue;
+    const resolved = resolveElementIntents(ancestor.openingElement, componentIntentCache);
+    if (!resolved) continue;
+    if (resolved.allowedChildIntents === void 0) continue;
+    return { resolved, element: ancestor };
+  }
+  return void 0;
+}
+function findNearestContext(ancestors, componentIntentCache) {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const ancestor = ancestors[i];
+    if (ancestor.type !== "JSXElement") continue;
+    const resolved = resolveElementIntents(ancestor.openingElement, componentIntentCache);
+    if (!resolved) continue;
+    if (resolved.context && resolved.context.length > 0) {
+      return { context: resolved.context, element: ancestor };
+    }
+  }
+  return void 0;
+}
+
+// src/rules/jsx-children-intents.ts
+var createRule = ESLintUtils.RuleCreator(
+  (name) => `https://github.com/xmlguy74/espcompose/blob/main/docs/rules/${name}.md`
+);
+var jsx_children_intents_default = createRule({
+  name: "jsx-children-intents",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce valid parent-child component nesting based on declared intents"
+    },
+    messages: {
+      invalidChildIntent: '"<{{ childTag }}>" with intents [{{ childIntents }}] cannot be a child of "<{{ parentTag }}>". Parent accepts: [{{ allowedIntents }}].',
+      noIntentsOnChild: '"<{{ childTag }}>" has no declared intents but its parent "<{{ parentTag }}>" requires children with intents: [{{ allowedIntents }}].',
+      missingContextIntent: '"<{{ childTag }}>" with intents [{{ childIntents }}] is missing required context [{{ requiredContext }}] established by "<{{ contextTag }}>".',
+      noIntentsForContext: '"<{{ childTag }}>" has no declared intents but is inside a context [{{ requiredContext }}] established by "<{{ contextTag }}>".'
+    },
+    schema: []
+  },
+  defaultOptions: [],
+  create(context) {
+    const componentIntentCache = /* @__PURE__ */ new Map();
+    return {
+      JSXElement(node) {
+        const { children } = node;
+        for (const child of children) {
+          if (child.type !== "JSXElement") continue;
+          const childOpeningElement = child.openingElement;
+          const childTagName = getJSXTagName(childOpeningElement);
+          const childResolved = resolveElementIntents(childOpeningElement, componentIntentCache);
+          const ancestors = context.sourceCode.getAncestors(node);
+          const fullAncestors = [...ancestors, node];
+          const constrainingParent = findConstrainingParent(fullAncestors, componentIntentCache);
+          if (constrainingParent) {
+            const { resolved: parentResolved, element: parentElement } = constrainingParent;
+            const parentTagName = getJSXTagName(parentElement.openingElement);
+            const allowed = parentResolved.allowedChildIntents;
+            if (!childResolved) {
+              if (isIntrinsicElement(childTagName)) {
+                context.report({
+                  node: childOpeningElement,
+                  messageId: "noIntentsOnChild",
+                  data: {
+                    childTag: childTagName,
+                    parentTag: parentTagName,
+                    allowedIntents: allowed.join(", ")
+                  }
+                });
+              }
+            } else {
+              const hasMatch = childResolved.intents.some((intent) => allowed.includes(intent));
+              if (!hasMatch) {
+                context.report({
+                  node: childOpeningElement,
+                  messageId: "invalidChildIntent",
+                  data: {
+                    childTag: childTagName,
+                    childIntents: childResolved.intents.join(", "),
+                    parentTag: parentTagName,
+                    allowedIntents: allowed.join(", ")
+                  }
+                });
+              }
+            }
+          }
+          if (childResolved?.contextTransparent) continue;
+          const nearestContext = findNearestContext(fullAncestors, componentIntentCache);
+          if (nearestContext) {
+            const { context: requiredContext, element: contextElement } = nearestContext;
+            const contextTagName = getJSXTagName(contextElement.openingElement);
+            if (!childResolved) {
+              if (isIntrinsicElement(childTagName)) {
+                context.report({
+                  node: childOpeningElement,
+                  messageId: "noIntentsForContext",
+                  data: {
+                    childTag: childTagName,
+                    requiredContext: requiredContext.join(", "),
+                    contextTag: contextTagName
+                  }
+                });
+              }
+            } else {
+              const missingContext = requiredContext.filter(
+                (ctx) => !childResolved.intents.includes(ctx)
+              );
+              if (missingContext.length > 0) {
+                context.report({
+                  node: childOpeningElement,
+                  messageId: "missingContextIntent",
+                  data: {
+                    childTag: childTagName,
+                    childIntents: childResolved.intents.join(", "),
+                    requiredContext: missingContext.join(", "),
+                    contextTag: contextTagName
+                  }
+                });
+              }
+            }
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/index.ts
+var plugin = {
+  meta: {
+    name: "@esphome/compose-eslint",
+    version: "0.0.1"
+  },
+  rules: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    "jsx-children-intents": jsx_children_intents_default
+  }
+};
+var recommended = [
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      "@esphome/compose-eslint": plugin
+    },
+    languageOptions: {
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+        ecmaFeatures: { jsx: true }
+      }
+    },
+    rules: {
+      // Demote to warning: the JSX factory import (ESPCompose) and top-level
+      // function declarations (which the compiler transforms into ESPHome
+      // <script> elements) appear unused to static analysis but are consumed
+      // at compile time.
+      "@typescript-eslint/no-unused-vars": ["warn", {
+        varsIgnorePattern: "^ESPCompose$"
+      }],
+      // Enforce valid parent-child component nesting based on declared intents.
+      "@esphome/compose-eslint/jsx-children-intents": "error"
+    }
+  },
+  {
+    ignores: ["**/dist/**", "**/node_modules/**", "**/.espcompose/**"]
+  }
+];
+var composeESLint = {
+  plugin,
+  recommended
+};
+var index_default = composeESLint;
+export {
+  index_default as default
+};

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@esphome/compose-eslint",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "ESLint plugin with custom rules for ESPHome Compose projects",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
   "exports": {
     ".": {
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     }
   },
   "files": [
@@ -21,24 +22,36 @@
   ],
   "author": "",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xmlguy74/espcompose.git",
+    "directory": "packages/eslint"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.0.0",
+    "typescript-eslint": "^8.0.0",
+    "@esphome/compose": "0.2.0"
+  },
   "peerDependencies": {
-    "eslint": ">=8.0.0"
+    "eslint": ">=9.0.0"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^7.0.0",
-    "@types/eslint": "^8.0.0",
-    "eslint": "^8.0.0",
+    "@typescript-eslint/rule-tester": "^8.0.0",
+    "eslint": "^9.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs --dts",
+    "build": "tsup src/index.ts --format esm --dts",
     "clean": "rimraf dist",
-    "lint": "eslint --ext .ts src",
-    "test": "echo \"No tests yet\""
+    "lint": "eslint src",
+    "test": "vitest run"
   }
 }

package/dist/index.d.ts

@@ -1,12 +0,0 @@
-import { ESLint } from 'eslint';
-
-/**
- * ESPHome TSX ESLint Plugin
- *
- * This package provides custom ESLint rules for enforcing
- * best practices and constraints in ESPHome TSX projects.
- */
-
-declare const plugin: ESLint.Plugin;
-
-export { plugin as default };

package/dist/index.js

@@ -1,21 +0,0 @@
-"use strict";
-
-// src/index.ts
-var plugin = {
-  meta: {
-    name: "@esphome-tsx/eslint-plugin",
-    version: "0.0.1"
-  },
-  rules: {
-    // Custom rules will be added here
-  },
-  configs: {
-    recommended: {
-      plugins: ["@esphome-tsx"],
-      rules: {
-        // Recommended rule configurations will be added here
-      }
-    }
-  }
-};
-module.exports = plugin;