@almadar/eslint-plugin 2.3.0 → 2.4.2

package/index.js

@@ -23,6 +23,13 @@ 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");
+
+// Behavior rules
+const behaviorNoOrganisms = require("./rules/behavior-no-organisms");
 
 // Service rules - Phase 1-3 (Implemented)
 const serviceLazySingleton = require("./rules/service-lazy-singleton");
@@ -73,6 +80,13 @@ 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,
+
+    // Behavior rules
+    "behavior-no-organisms": behaviorNoOrganisms,
 
     // Service rules - Phase 1-3
     "service-lazy-singleton": serviceLazySingleton,
@@ -115,6 +129,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",
@@ -125,12 +140,16 @@ plugin.configs.recommended = {
     "almadar/template-extends-base": "warn",
     "almadar/require-translate": "warn",
 
+    // Behavior rules — restrict to atoms/molecules only
+    "almadar/behavior-no-organisms": "error",
+
     // Organism rules — enforce dumb organism pattern
     "almadar/organism-no-data-state": "error",
     "almadar/organism-no-auto-fetch": "error",
     "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 +189,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",
   },
 };
 
@@ -219,4 +239,17 @@ plugin.configs["services-strict"] = {
   },
 };
 
+// Behaviors config — lint .orb behavior schemas for pattern tier compliance
+// Requires: jsonc-eslint-parser (pnpm add -D jsonc-eslint-parser)
+// Usage in eslint.config.js: { files: ["**/*.orb"], ...almadar.configs.behaviors }
+plugin.configs.behaviors = {
+  plugins: { almadar: plugin },
+  languageOptions: {
+    parser: require("jsonc-eslint-parser"),
+  },
+  rules: {
+    "almadar/behavior-no-organisms": "error",
+  },
+};
+
 module.exports = plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/eslint-plugin",
-  "version": "2.3.0",
+  "version": "2.4.2",
   "private": false,
   "description": "Custom ESLint rules for Almadar component architecture",
   "main": "index.js",
@@ -12,11 +12,20 @@
   "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"
+  },
+  "dependencies": {
+    "jsonc-eslint-parser": "3.1.0"
+  },
+  "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/behavior-no-organisms.js

@@ -0,0 +1,166 @@
+"use strict";
+
+/**
+ * behavior-no-organisms
+ *
+ * Behaviors (.orb files in behaviors/) must only use atom and molecule patterns.
+ * Organisms and templates are forbidden, with exceptions for:
+ *   - Game-related patterns (category "game" in component-mapping.json)
+ *   - form / form-section (explicitly allowed by convention)
+ *
+ * Requires: jsonc-eslint-parser configured for *.orb files.
+ *
+ * To regenerate BLOCKED_PATTERNS from component-mapping.json:
+ *   node -e "
+ *     const m = require('../almadar-patterns/src/component-mapping.json').mappings;
+ *     const blocked = Object.entries(m)
+ *       .filter(([k, v]) =>
+ *         (v.importPath.includes('/organisms/') || v.importPath.includes('/templates/'))
+ *         && v.category !== 'game'
+ *         && !['form', 'form-section'].includes(k))
+ *       .map(([k]) => k);
+ *     console.log(JSON.stringify(blocked, null, 2));
+ *   "
+ */
+
+// Organism patterns: importPath contains /organisms/, category !== "game"
+// Template patterns: importPath contains /templates/, not game-related
+// Excludes: form, form-section (allowed by convention)
+const BLOCKED_PATTERNS = new Set([
+  // ── Organisms (non-game, non-form) ────────────────────────────────
+  "page-header",
+  "entity-list",
+  "entity-table",
+  "entity-cards",
+  "stats",
+  "detail-panel",
+  "wizard-container",
+  "confirm-dialog",
+  "master-detail",
+  "dashboard-grid",
+  "runtime-debugger",
+  "button-pattern",
+  "custom-pattern",
+  "drawer-slot",
+  "header",
+  "layout-pattern",
+  "modal-slot",
+  "navigation",
+  "orbital-visualization",
+  "section",
+  "sidebar",
+  "split",
+  "table",
+  "toast-slot",
+  "u-i-slot-renderer",
+  "split-pane",
+  "tabbed-container",
+  "collapsible-section",
+  "camera3-d",
+  "lighting3-d",
+  "scene3-d",
+  "canvas3-d-error-boundary",
+  "canvas3-d-loading-state",
+  "model-loader",
+  "physics-object3-d",
+  "feature-renderer",
+  "feature-renderer3-d",
+  "unit-renderer",
+  "trait-slot",
+  "trait-state-viewer",
+  "content-renderer",
+  "jazari-state-machine",
+  "state-machine-view",
+  "book-chapter-view",
+  "book-cover-page",
+  "book-nav-bar",
+  "book-table-of-contents",
+  "book-viewer",
+  "simulation-controls",
+  "simulation-graph",
+  "chart",
+  "timeline",
+  "media-gallery",
+  "signature-pad",
+  "document-viewer",
+  "graph-canvas",
+  "code-viewer",
+  "event-log",
+  "object-rule-panel",
+  "rule-editor",
+  "action-palette",
+  "sequence-bar",
+  "code-view",
+  "state-architect-board",
+  "state-node",
+  "transition-arrow",
+  "variable-panel",
+
+  // ── Templates (non-game) ──────────────────────────────────────────
+  "auth-layout",
+  "counter-template",
+  "dashboard-layout",
+  "generic-app-template",
+]);
+
+// Alternative names that map to the same organism
+const ALIASES = {
+  form: null, // explicitly allowed
+  "form-section": null, // explicitly allowed
+};
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Behavior schemas must only use atom and molecule patterns. " +
+        "Organisms and templates (except games and form-section) are forbidden.",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      blockedPattern:
+        'Pattern "{{pattern}}" is an organism/template. ' +
+        "Behaviors must only use atoms and molecules. " +
+        "Replace with a molecule-level equivalent or restructure the schema.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename || context.getFilename();
+
+    // Only apply to .orb files inside behaviors/ directories
+    if (!filename.endsWith(".orb") || !filename.includes("behaviors")) {
+      return {};
+    }
+
+    return {
+      // jsonc-eslint-parser provides JSONProperty AST nodes
+      JSONProperty(node) {
+        // Look for "type": "<pattern-name>" properties
+        if (
+          node.key &&
+          node.key.type === "JSONLiteral" &&
+          node.key.value === "type" &&
+          node.value &&
+          node.value.type === "JSONLiteral" &&
+          typeof node.value.value === "string"
+        ) {
+          const pattern = node.value.value;
+
+          // Skip explicitly allowed aliases
+          if (pattern in ALIASES) return;
+
+          if (BLOCKED_PATTERNS.has(pattern)) {
+            context.report({
+              node: node.value,
+              messageId: "blockedPattern",
+              data: { pattern },
+            });
+          }
+        }
+      },
+    };
+  },
+};

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(/^\.\//, "")) ||