@almadar/eslint-plugin 2.1.1

package/rules/organism-no-callback-props.js

@@ -0,0 +1,57 @@
+"use strict";
+const { isOrganism, isStoryFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow callback props (onXxx) in organism interfaces",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noCallbackProp: "Organism prop '{{propName}}' in '{{interfaceName}}' is a callback. Use a declarative event string prop instead (e.g., '{{suggestion}}').",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isOrganism(filename) || isStoryFile(filename)) return {};
+
+    // Whitelist Form.tsx (needs onFieldChange)
+    if (/\/Form\.tsx$/.test(filename)) return {};
+
+    const CALLBACK_PATTERN = /^on[A-Z]/;
+    const SUGGESTION_MAP = {
+      onSort: "sortEvent",
+      onSearch: "searchEvent",
+      onPageChange: "paginateEvent",
+      onSelectionChange: "selectEvent",
+      onRowClick: "viewEvent or navigatesTo",
+      onCardClick: "viewEvent or navigatesTo",
+      onItemAction: "itemActions[].event",
+      onClose: "closeEvent",
+    };
+
+    return {
+      TSPropertySignature(node) {
+        // Only check inside *Props interfaces
+        const parent = node.parent;
+        if (parent?.type !== "TSInterfaceBody") return;
+        const interfaceNode = parent.parent;
+        if (interfaceNode?.type !== "TSInterfaceDeclaration") return;
+        const interfaceName = interfaceNode.id?.name;
+        if (!interfaceName?.endsWith("Props")) return;
+
+        const propName = node.key?.type === "Identifier" ? node.key.name : null;
+        if (!propName || !CALLBACK_PATTERN.test(propName)) return;
+
+        const suggestion = SUGGESTION_MAP[propName] || propName.replace(/^on/, "").toLowerCase() + "Event";
+        context.report({
+          node,
+          messageId: "noCallbackProp",
+          data: { propName, interfaceName, suggestion },
+        });
+      },
+    };
+  },
+};

package/rules/organism-no-data-state.js

@@ -0,0 +1,50 @@
+"use strict";
+const { isOrganism, isStoryFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow data-related useState in organisms",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noDataState: "Organism '{{component}}' must not manage '{{stateName}}' state internally. Receive it via props from the trait's render-ui instead.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isOrganism(filename) || isStoryFile(filename)) return {};
+
+    // Whitelist Form.tsx
+    if (/\/Form\.tsx$/.test(filename)) return {};
+
+    const DATA_STATE_PATTERN = /^(sort|filter|search|page|pagination|selected|query|paginationParams|searchTerm|searchQuery|filters)/i;
+
+    return {
+      VariableDeclarator(node) {
+        // Match: const [stateName, setStateName] = useState(...)
+        if (
+          node.init?.type === "CallExpression" &&
+          node.init.callee?.type === "Identifier" &&
+          node.init.callee.name === "useState" &&
+          node.id?.type === "ArrayPattern" &&
+          node.id.elements?.[0]?.type === "Identifier"
+        ) {
+          const stateName = node.id.elements[0].name;
+          if (DATA_STATE_PATTERN.test(stateName)) {
+            // Derive component name from filename
+            const match = filename.match(/\/([^/]+)\.tsx?$/);
+            const component = match ? match[1] : "Unknown";
+            context.report({
+              node,
+              messageId: "noDataState",
+              data: { stateName, component },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/organism-rendering-state-only.js

@@ -0,0 +1,47 @@
+"use strict";
+const { isStoryFile } = require("../utils/helpers");
+
+function isGameOrganism(filename) {
+  return /\/organisms\/game\//.test(filename);
+}
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Warn if game organisms have non-rendering useState",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      nonRenderingState: "Game organism useState '{{stateName}}' does not match a rendering-only pattern. Extract game-logic state to a hook.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isGameOrganism(filename) || isStoryFile(filename)) return {};
+
+    const RENDERING_ONLY_PATTERN = /^(hover|isHover|isDrag|isShak|tooltip|viewport|moving|displayed|isTyp|phase|visible|flash|shakeOffset|internalError|activeButtons|activeDirections|isPressed|openActionMenu|canvas|camera|animate|render|frame|scroll|zoom|pan|cursor|highlight|glow|fade|opacity|offset|position|dimension|scale|rotation)/i;
+
+    return {
+      VariableDeclarator(node) {
+        if (
+          node.init?.type === "CallExpression" &&
+          node.init.callee?.type === "Identifier" &&
+          node.init.callee.name === "useState" &&
+          node.id?.type === "ArrayPattern" &&
+          node.id.elements?.[0]?.type === "Identifier"
+        ) {
+          const stateName = node.id.elements[0].name;
+          if (!RENDERING_ONLY_PATTERN.test(stateName)) {
+            context.report({
+              node,
+              messageId: "nonRenderingState",
+              data: { stateName },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/require-closed-circuit-props.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const { isOrganism } = require("../utils/helpers");
+
+const REQUIRED_PROPS = ["className"];
+const RECOMMENDED_PROPS = ["isLoading", "error", "entity", "data", "sortBy", "sortDirection", "page", "pageSize", "totalCount", "searchValue"];
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require closed circuit base props (className, isLoading, error, entity) on organism prop interfaces",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      missingProp:
+        "Organism prop interface '{{interface}}' is missing '{{prop}}'. Closed circuit requires: className, isLoading, error, entity.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    if (!isOrganism(filename)) return {};
+    if (!/\.(tsx|jsx|ts)$/.test(filename)) return {};
+
+    return {
+      TSInterfaceDeclaration(node) {
+        // Only check interfaces ending with Props
+        if (!node.id || !/Props$/.test(node.id.name)) return;
+
+        const declaredProps = new Set();
+
+        // Collect props from the interface body
+        for (const member of node.body.body) {
+          if (
+            member.type === "TSPropertySignature" &&
+            member.key &&
+            member.key.type === "Identifier"
+          ) {
+            declaredProps.add(member.key.name);
+          }
+        }
+
+        // Check for extends that might provide the props
+        if (node.extends && node.extends.length > 0) {
+          // If it extends something, assume it might get props from parent
+          // We can't easily resolve what the parent provides, so only
+          // flag if it extends nothing and is missing props
+          return;
+        }
+
+        const allExpected = [...REQUIRED_PROPS, ...RECOMMENDED_PROPS];
+        for (const prop of allExpected) {
+          if (!declaredProps.has(prop)) {
+            context.report({
+              node: node.id,
+              messageId: "missingProp",
+              data: {
+                interface: node.id.name,
+                prop,
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/require-display-name.js

@@ -0,0 +1,83 @@
+"use strict";
+
+const { isStoryFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require displayName on exported React components",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      missingDisplayName:
+        "Component '{{name}}' is missing displayName. Add: {{name}}.displayName = '{{name}}';",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    if (isStoryFile(filename)) return {};
+    // Only check design-system and @almadar/ui component files
+    if (
+      !/(design-system|almadar-ui\/components)\//.test(filename) ||
+      !/\.(tsx|jsx)$/.test(filename)
+    ) {
+      return {};
+    }
+
+    const exportedComponents = [];
+    const displayNames = new Set();
+
+    return {
+      // Track: export const Foo = ...
+      ExportNamedDeclaration(node) {
+        if (node.declaration && node.declaration.type === "VariableDeclaration") {
+          for (const decl of node.declaration.declarations) {
+            if (
+              decl.id.type === "Identifier" &&
+              /^[A-Z]/.test(decl.id.name)
+            ) {
+              exportedComponents.push(decl.id);
+            }
+          }
+        }
+        // export function Foo
+        if (
+          node.declaration &&
+          node.declaration.type === "FunctionDeclaration" &&
+          node.declaration.id &&
+          /^[A-Z]/.test(node.declaration.id.name)
+        ) {
+          exportedComponents.push(node.declaration.id);
+        }
+      },
+
+      // Track: Foo.displayName = '...'
+      AssignmentExpression(node) {
+        if (
+          node.left.type === "MemberExpression" &&
+          node.left.property.type === "Identifier" &&
+          node.left.property.name === "displayName" &&
+          node.left.object.type === "Identifier"
+        ) {
+          displayNames.add(node.left.object.name);
+        }
+      },
+
+      "Program:exit"() {
+        for (const comp of exportedComponents) {
+          if (!displayNames.has(comp.name)) {
+            context.report({
+              node: comp,
+              messageId: "missingDisplayName",
+              data: { name: comp.name },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/require-event-bus.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const { isTemplateFile, isStoryFile, isOrganism } = require("../utils/helpers");
+
+/**
+ * Callback props that have declarative equivalents in @almadar/ui.
+ */
+const CALLBACK_TO_DECLARATIVE = {
+  onClick: "action",
+  onClose: "closeEvent",
+  onDismiss: "dismissEvent",
+  onRetry: "retryEvent",
+  onSubmit: "submitEvent",
+};
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Prefer declarative event props over callback props on @almadar/ui components",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      preferDeclarative:
+        "Prefer declarative '{{declarative}}' prop over '{{callback}}' for closed circuit integration.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    // Enforce in templates and organisms
+    if (!isTemplateFile(filename) && !isOrganism(filename)) return {};
+
+    // Stories use callbacks for testing
+    if (isStoryFile(filename)) return {};
+
+    return {
+      JSXAttribute(node) {
+        if (!node.name || node.name.type !== "JSXIdentifier") return;
+
+        const propName = node.name.name;
+        const declarative = CALLBACK_TO_DECLARATIVE[propName];
+
+        if (!declarative) return;
+
+        // Only flag if the value is a function expression
+        if (
+          node.value &&
+          node.value.type === "JSXExpressionContainer" &&
+          (node.value.expression.type === "ArrowFunctionExpression" ||
+           node.value.expression.type === "FunctionExpression")
+        ) {
+          context.report({
+            node,
+            messageId: "preferDeclarative",
+            data: { declarative, callback: propName },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/require-stories.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { isStoryFile, isOrganism, isTemplateFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require .stories.tsx file for organism and template components",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      missingStory:
+        "Component '{{name}}' is missing a .stories.tsx file. Every organism and template needs Storybook coverage.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    // Only check organisms and templates
+    if (!isOrganism(filename) && !isTemplateFile(filename)) return {};
+    if (isStoryFile(filename)) return {};
+    if (!/\.(tsx|jsx)$/.test(filename)) return {};
+
+    // Skip index files
+    if (/index\.(tsx|jsx)$/.test(filename)) return {};
+
+    return {
+      Program(node) {
+        const dir = path.dirname(filename);
+        const base = path.basename(filename, path.extname(filename));
+
+        // Check for sibling .stories.tsx
+        const storyFile = path.join(dir, `${base}.stories.tsx`);
+        const storyFileJsx = path.join(dir, `${base}.stories.jsx`);
+
+        // Also check stories/ subdirectory
+        const storiesDir = path.join(dir, "stories", `${base}.stories.tsx`);
+
+        if (
+          !fs.existsSync(storyFile) &&
+          !fs.existsSync(storyFileJsx) &&
+          !fs.existsSync(storiesDir)
+        ) {
+          context.report({
+            node,
+            messageId: "missingStory",
+            data: { name: base },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/require-translate.js

@@ -0,0 +1,106 @@
+"use strict";
+
+const { isStoryFile, isTemplateFile, isAtomOrMolecule, isOrganism } = require("../utils/helpers");
+
+/**
+ * Check if a file is inside a molecules/ directory.
+ */
+function isMolecule(filename) {
+  return /\/molecules\//.test(filename);
+}
+
+/**
+ * Check if a file is inside an atoms/ directory (but NOT molecules/).
+ */
+function isAtom(filename) {
+  return /\/atoms\//.test(filename) && !isMolecule(filename);
+}
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require useTranslate import in organism and molecule components for i18n",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      missingUseTranslate:
+        "Component '{{name}}' should import useTranslate for i18n. Add: const { t } = useTranslate();",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    // Only applies to .tsx files in design-system/ or almadar-ui/components/
+    if (!/\.(tsx)$/.test(filename)) return {};
+    if (!/(design-system|almadar-ui\/components)\//.test(filename)) return {};
+
+    // Skip story files, atom files, template files
+    if (isStoryFile(filename)) return {};
+    if (isAtom(filename)) return {};
+    if (isTemplateFile(filename)) return {};
+
+    // Only check organisms and molecules
+    if (!isOrganism(filename) && !isMolecule(filename)) return {};
+
+    let hasUseTranslateImport = false;
+    const exportedComponents = [];
+
+    return {
+      // Check for import of useTranslate from @almadar/ui or relative path
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (
+          source === "@almadar/ui" ||
+          /useTranslate/.test(source)
+        ) {
+          for (const specifier of node.specifiers) {
+            if (
+              specifier.type === "ImportSpecifier" &&
+              specifier.imported.name === "useTranslate"
+            ) {
+              hasUseTranslateImport = true;
+            }
+          }
+        }
+      },
+
+      // Track exported components: export const Foo = ...
+      ExportNamedDeclaration(node) {
+        if (node.declaration && node.declaration.type === "VariableDeclaration") {
+          for (const decl of node.declaration.declarations) {
+            if (
+              decl.id.type === "Identifier" &&
+              /^[A-Z]/.test(decl.id.name)
+            ) {
+              exportedComponents.push(decl.id);
+            }
+          }
+        }
+        // export function Foo
+        if (
+          node.declaration &&
+          node.declaration.type === "FunctionDeclaration" &&
+          node.declaration.id &&
+          /^[A-Z]/.test(node.declaration.id.name)
+        ) {
+          exportedComponents.push(node.declaration.id);
+        }
+      },
+
+      "Program:exit"() {
+        if (hasUseTranslateImport) return;
+        if (exportedComponents.length === 0) return;
+
+        // Report on the first exported component
+        context.report({
+          node: exportedComponents[0],
+          messageId: "missingUseTranslate",
+          data: { name: exportedComponents[0].name },
+        });
+      },
+    };
+  },
+};

package/rules/service-event-name-screaming.js

@@ -0,0 +1,73 @@
+"use strict";
+
+const SCREAMING_SNAKE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/;
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "EventBus event names must use SCREAMING_SNAKE_CASE to match .orb schema conventions",
+      category: "Almadar Services",
+    },
+    messages: {
+      badEventName:
+        "Event name '{{name}}' must be SCREAMING_SNAKE_CASE (e.g., 'LLM_REQUEST_COMPLETE'). The .orb schema uses this convention — mismatched names mean listeners won't fire.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+
+        // Match: eventBus.emit('...') or getServerEventBus().emit('...')
+        // Skip generic .emit() calls on non-EventBus objects (Node EventEmitter, etc.)
+        if (
+          callee.type !== "MemberExpression" ||
+          callee.property.type !== "Identifier" ||
+          callee.property.name !== "emit" ||
+          node.arguments.length === 0
+        ) return;
+
+        // Only flag calls on objects that look like EventBus instances
+        const obj = callee.object;
+        const isEventBus =
+          // Direct: eventBus.emit, serverEventBus.emit, bus.emit
+          (obj.type === "Identifier" && /[Ee]vent[Bb]us/.test(obj.name)) ||
+          // Getter: getServerEventBus().emit()
+          (obj.type === "CallExpression" &&
+           obj.callee.type === "Identifier" &&
+           /[Ee]vent[Bb]us/.test(obj.callee.name)) ||
+          // this.eventBus.emit or this.bus.emit (inside service classes)
+          (obj.type === "MemberExpression" &&
+           obj.property.type === "Identifier" &&
+           /[Ee]vent[Bb]us|^bus$/.test(obj.property.name));
+
+        if (!isEventBus) return;
+
+        const firstArg = node.arguments[0];
+
+        // Only check string literals
+        if (firstArg.type !== "Literal" || typeof firstArg.value !== "string") return;
+
+        const eventName = firstArg.value;
+
+        // Skip UI:* events (handled by event-naming-convention rule)
+        if (eventName.startsWith("UI:")) return;
+
+        // Skip wildcard
+        if (eventName === "*") return;
+
+        if (!SCREAMING_SNAKE.test(eventName)) {
+          context.report({
+            node: firstArg,
+            messageId: "badEventName",
+            data: { name: eventName },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/service-eventbus-singleton.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const path = require("path");
+
+/**
+ * Files that are allowed to construct EventBus instances.
+ */
+const ALLOWED_FILES = new Set([
+  "eventBus.ts",
+  "eventBus.js",
+  "eventBusTransport.ts",
+  "eventBusTransport.js",
+  "event-bus.ts",
+  "event-bus.js",
+]);
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prevent creating multiple EventBus instances — use the singleton from eventBus.ts",
+      category: "Almadar Services",
+    },
+    messages: {
+      duplicateEventBus:
+        "Don't create a new EventBus here. Import the singleton from your eventBus module. Split buses mean events emitted by the .orb schema never reach listeners on this bus.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    const basename = path.basename(filename);
+
+    // Allow EventBus construction in dedicated files
+    if (ALLOWED_FILES.has(basename)) return {};
+
+    // Also allow in test files
+    if (/\.(test|spec)\.(ts|tsx|js|jsx)$/.test(filename)) return {};
+
+    return {
+      NewExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "EventBus"
+        ) {
+          context.report({ node, messageId: "duplicateEventBus" });
+        }
+      },
+    };
+  },
+};