@almadar/eslint-plugin 2.3.0 → 2.4.1

package/index.js

@@ -23,6 +23,10 @@ const organismNoAutoFetch = require("./rules/organism-no-auto-fetch");
 const organismNoCallbackProps = require("./rules/organism-no-callback-props");
 const organismExtendsEntityDisplay = require("./rules/organism-extends-entity-display");
 const organismRenderingStateOnly = require("./rules/organism-rendering-state-only");
+const organismRequireEntityRow = require("./rules/organism-require-entity-row");
+
+// Atom/molecule rules
+const atomMoleculeNoEntityProp = require("./rules/atom-molecule-no-entity-prop");
 
 // Service rules - Phase 1-3 (Implemented)
 const serviceLazySingleton = require("./rules/service-lazy-singleton");
@@ -73,6 +77,10 @@ const plugin = {
     "organism-no-callback-props": organismNoCallbackProps,
     "organism-extends-entity-display": organismExtendsEntityDisplay,
     "organism-rendering-state-only": organismRenderingStateOnly,
+    "organism-require-entity-row": organismRequireEntityRow,
+
+    // Atom/molecule rules
+    "atom-molecule-no-entity-prop": atomMoleculeNoEntityProp,
 
     // Service rules - Phase 1-3
     "service-lazy-singleton": serviceLazySingleton,
@@ -115,6 +123,7 @@ plugin.configs.recommended = {
     "almadar/no-entity-string-type": "error",
     "almadar/no-import-generated": "error",
     "almadar/no-use-navigate": "error",
+    "almadar/atom-molecule-no-entity-prop": "error",
 
     // Warn-level — conventions that should be followed
     "almadar/require-event-bus": "warn",
@@ -131,6 +140,7 @@ plugin.configs.recommended = {
     "almadar/organism-no-callback-props": "error",
     "almadar/organism-extends-entity-display": "error",
     "almadar/organism-rendering-state-only": "warn",
+    "almadar/organism-require-entity-row": "error",
   },
 };
 
@@ -170,6 +180,7 @@ plugin.configs.organisms = {
     "almadar/organism-rendering-state-only": "warn",
     "almadar/require-event-bus": "error",
     "almadar/require-closed-circuit-props": "error",
+    "almadar/organism-require-entity-row": "error",
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/eslint-plugin",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "private": false,
   "description": "Custom ESLint rules for Almadar component architecture",
   "main": "index.js",
@@ -12,11 +12,17 @@
   "peerDependencies": {
     "eslint": ">=8.0.0"
   },
+  "devDependencies": {
+    "eslint": "10.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/almadar-io/almadar-eslint.git"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint index.js rules/ utils/"
   }
 }

package/rules/atom-molecule-no-entity-prop.js

@@ -0,0 +1,82 @@
+"use strict";
+const { isAtomOrMolecule, isStoryFile } = require("../utils/helpers");
+
+/**
+ * Exceptions: molecules that legitimately need entity-like array data props
+ * because they are data-iteration components (mini-organisms promoted to molecules).
+ */
+const EXCEPTED_FILES = new Set([
+  "DataGrid",
+  "DataList",
+  "ButtonGroup",    // uses entity as string name for event context
+  "FilterGroup",    // uses entity as string name for filter events
+  "SearchInput",    // uses entity as string name for search events
+]);
+
+function isExcepted(filename) {
+  for (const name of EXCEPTED_FILES) {
+    if (filename.endsWith(`/${name}.tsx`) || filename.endsWith(`/${name}.jsx`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow 'entity' prop on atoms and molecules. Atoms/molecules are pure UI building blocks that accept normal typed props. Only organisms and templates should accept 'entity'.",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noEntityProp:
+        "Atoms and molecules must not accept an 'entity' prop. Use normal typed props instead (e.g., markers, nodes, items). Only organisms and templates should be entity-aware.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isAtomOrMolecule(filename)) return {};
+    if (isStoryFile(filename)) return {};
+    if (isExcepted(filename)) return {};
+
+    return {
+      // Check interface declarations: interface FooProps { entity?: ... }
+      TSPropertySignature(node) {
+        if (
+          node.key?.type === "Identifier" &&
+          node.key.name === "entity"
+        ) {
+          // Only flag if inside an interface ending with "Props"
+          const parent = node.parent?.parent;
+          if (
+            parent?.type === "TSInterfaceDeclaration" &&
+            parent.id?.name?.endsWith("Props")
+          ) {
+            context.report({ node, messageId: "noEntityProp" });
+          }
+        }
+      },
+
+      // Check type alias declarations: type FooProps = { entity?: ... }
+      TSTypeAliasDeclaration(node) {
+        if (!node.id?.name?.endsWith("Props")) return;
+        const typeAnnotation = node.typeAnnotation;
+        if (typeAnnotation?.type !== "TSTypeLiteral") return;
+
+        for (const member of typeAnnotation.members) {
+          if (
+            member.type === "TSPropertySignature" &&
+            member.key?.type === "Identifier" &&
+            member.key.name === "entity"
+          ) {
+            context.report({ node: member, messageId: "noEntityProp" });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/organism-require-entity-row.js

@@ -0,0 +1,179 @@
+"use strict";
+const { isOrganism, isStoryFile, isGameOrganism } = require("../utils/helpers");
+
+/**
+ * Find the outermost JSX element returned from a .map() callback.
+ * Handles: arrow with expression body, arrow with block body + return,
+ * and conditional expressions.
+ */
+function getReturnedJSX(callbackBody) {
+  if (
+    callbackBody.type === "JSXElement" ||
+    callbackBody.type === "JSXFragment"
+  ) {
+    return callbackBody;
+  }
+
+  if (callbackBody.type === "ConditionalExpression") {
+    return (
+      getReturnedJSX(callbackBody.consequent) ||
+      getReturnedJSX(callbackBody.alternate)
+    );
+  }
+
+  if (callbackBody.type === "BlockStatement") {
+    for (const stmt of callbackBody.body) {
+      if (stmt.type === "ReturnStatement" && stmt.argument) {
+        const jsx = getReturnedJSX(stmt.argument);
+        if (jsx) return jsx;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a JSX element has a specific attribute (by name).
+ */
+function hasJSXAttribute(jsxElement, attrName) {
+  if (jsxElement.type !== "JSXElement") return false;
+  return jsxElement.openingElement.attributes.some(
+    (attr) =>
+      attr.type === "JSXAttribute" &&
+      attr.name?.type === "JSXIdentifier" &&
+      attr.name.name === attrName
+  );
+}
+
+/**
+ * Check if a JSX element has key={param.id} where param is the callback's
+ * first parameter. This distinguishes entity iteration (key={hero.id})
+ * from utility iteration (key={field}, key={index}, key={actionIdx}).
+ */
+function hasEntityKeyPattern(jsxElement, callbackParam) {
+  if (jsxElement.type !== "JSXElement") return false;
+  if (!callbackParam) return false;
+
+  // Get the callback parameter name
+  const paramName =
+    callbackParam.type === "Identifier"
+      ? callbackParam.name
+      : callbackParam.type === "ObjectPattern"
+        ? null // destructured param, check differently
+        : null;
+
+  for (const attr of jsxElement.openingElement.attributes) {
+    if (attr.type !== "JSXAttribute") continue;
+    if (attr.name?.type !== "JSXIdentifier" || attr.name.name !== "key") continue;
+
+    const value = attr.value;
+    if (!value || value.type !== "JSXExpressionContainer") continue;
+
+    const expr = value.expression;
+
+    // key={param.id} pattern
+    if (
+      paramName &&
+      expr.type === "MemberExpression" &&
+      expr.object?.type === "Identifier" &&
+      expr.object.name === paramName &&
+      expr.property?.type === "Identifier" &&
+      expr.property.name === "id"
+    ) {
+      return true;
+    }
+
+    // key={param?.id} optional chaining
+    if (
+      paramName &&
+      expr.type === "ChainExpression" &&
+      expr.expression?.type === "MemberExpression" &&
+      expr.expression.object?.type === "Identifier" &&
+      expr.expression.object.name === paramName &&
+      expr.expression.property?.type === "Identifier" &&
+      expr.expression.property.name === "id"
+    ) {
+      return true;
+    }
+
+    // Destructured: key={id} when param is { id, ... }
+    if (
+      callbackParam.type === "ObjectPattern" &&
+      expr.type === "Identifier" &&
+      expr.name === "id"
+    ) {
+      // Verify 'id' is actually destructured from the param
+      const hasId = callbackParam.properties.some(
+        (p) =>
+          p.type === "Property" &&
+          p.key?.type === "Identifier" &&
+          p.key.name === "id"
+      );
+      if (hasId) return true;
+    }
+  }
+
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require data-entity-row attribute on the outermost JSX element returned from .map() in organisms when iterating over entities",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      missingEntityRow:
+        "Entity row element in .map() is missing 'data-entity-row' attribute. Add it to the root DOM element of each entity card so the verification system can detect entity rows.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+
+    if (!isOrganism(filename) || isStoryFile(filename)) return {};
+    if (isGameOrganism(filename)) return {};
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== "MemberExpression" ||
+          node.callee.property.type !== "Identifier" ||
+          node.callee.property.name !== "map"
+        ) {
+          return;
+        }
+
+        const callback = node.arguments[0];
+        if (!callback) return;
+
+        let body;
+        if (
+          callback.type === "ArrowFunctionExpression" ||
+          callback.type === "FunctionExpression"
+        ) {
+          body = callback.body;
+        } else {
+          return;
+        }
+
+        const jsxElement = getReturnedJSX(body);
+        if (!jsxElement || jsxElement.type !== "JSXElement") return;
+
+        // Only flag entity iteration: key={param.id} pattern
+        const callbackParam = callback.params[0];
+        if (!hasEntityKeyPattern(jsxElement, callbackParam)) return;
+
+        if (!hasJSXAttribute(jsxElement, "data-entity-row")) {
+          context.report({
+            node: jsxElement.openingElement,
+            messageId: "missingEntityRow",
+          });
+        }
+      },
+    };
+  },
+};

package/rules/require-translate.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const { isStoryFile, isTemplateFile, isAtomOrMolecule, isOrganism } = require("../utils/helpers");
+const { isStoryFile, isTemplateFile, isOrganism } = require("../utils/helpers");
 
 /**
  * Check if a file is inside a molecules/ directory.

package/rules/service-barrel-complete.js

@@ -40,7 +40,7 @@ module.exports = {
   create(context) {
     const options = context.options[0] || {};
     const barrelFileName = options.barrelFile || "index.ts";
-    const ignorePrivate = options.ignorePrivate !== false;
+    void options.ignorePrivate;
 
     const filename = context.filename;
     const dir = path.dirname(filename);
@@ -60,7 +60,7 @@ module.exports = {
     let barrelContent = "";
     try {
       barrelContent = fs.readFileSync(barrelPath, "utf-8");
-    } catch (err) {
+    } catch {
       return {};
     }
 

package/rules/service-no-inline-queries.js

@@ -60,11 +60,11 @@ module.exports = {
       },
 
       // Check for Express route handler patterns
-      "CallExpression[callee.object.name='app'][callee.property.name=/^(get|post|put|delete|patch)$/]"(node) {
+      "CallExpression[callee.object.name='app'][callee.property.name=/^(get|post|put|delete|patch)$/]"(_node) {
         hasRouteHandlerPattern = true;
       },
 
-      "CallExpression[callee.object.name='router'][callee.property.name=/^(get|post|put|delete|patch)$/]"(node) {
+      "CallExpression[callee.object.name='router'][callee.property.name=/^(get|post|put|delete|patch)$/]"(_node) {
         hasRouteHandlerPattern = true;
       },
 

package/rules/service-no-workspace-refs.js

@@ -51,7 +51,7 @@ module.exports = {
             continue;
           }
 
-          for (const [name, version] of Object.entries(deps)) {
+          for (const [, version] of Object.entries(deps)) {
             // Check for workspace:*
             if (version === "workspace:*" || version === "workspace:") {
               context.report({

package/rules/service-subpath-match-tsup.js

@@ -67,12 +67,8 @@ module.exports = {
         const exports = pkg.exports || {};
         
         // Check each export has a corresponding tsup entry
-        for (const [exportPath, exportConfig] of Object.entries(exports)) {
+        for (const [exportPath] of Object.entries(exports)) {
           if (exportPath.startsWith("./")) {
-            const expectedPattern = exportPath === "." 
-              ? "index.js" 
-              : `${exportPath.replace(/^\.\//, "/")}.js`;
-            
             // Check if there's a matching entry in tsup
             const hasMatchingEntry = tsupContent.includes(exportPath.replace(/^\.\//, "src/")) ||
                                     tsupContent.includes(exportPath.replace(/^\.\//, "")) ||