@almadar/eslint-plugin 2.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almadar Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @almadar/eslint
+
+> Custom ESLint rules for Almadar component architecture
+
+Part of the [Almadar](https://github.com/almadar-io/almadar) platform.
+
+## Installation
+
+```bash
+npm install @almadar/eslint
+```
+
+## Usage
+
+```typescript
+import { /* ... */ } from '@almadar/eslint';
+```
+
+## API
+
+<!-- Document public exports here -->
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,178 @@
+"use strict";
+
+const noRawDomElements = require("./rules/no-raw-dom-elements");
+const templateNoHooks = require("./rules/template-no-hooks");
+const templateNoCallbacks = require("./rules/template-no-callbacks");
+const templateNoLocalVariables = require("./rules/template-no-local-variables");
+const templateNoIteration = require("./rules/template-no-iteration");
+const templateSerializableProps = require("./rules/template-serializable-props");
+const noTypeProp = require("./rules/no-type-prop");
+const noAsAny = require("./rules/no-as-any");
+const noImportGenerated = require("./rules/no-import-generated");
+const requireEventBus = require("./rules/require-event-bus");
+const requireDisplayName = require("./rules/require-display-name");
+const requireClosedCircuitProps = require("./rules/require-closed-circuit-props");
+const requireStories = require("./rules/require-stories");
+const eventNamingConvention = require("./rules/event-naming-convention");
+const templateExtendsBase = require("./rules/template-extends-base");
+const requireTranslate = require("./rules/require-translate");
+const organismNoDataState = require("./rules/organism-no-data-state");
+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");
+
+// Service rules
+const serviceLazySingleton = require("./rules/service-lazy-singleton");
+const serviceSingletonResettable = require("./rules/service-singleton-resettable");
+const serviceNoModuleSideEffects = require("./rules/service-no-module-side-effects");
+const serviceEventbusSingleton = require("./rules/service-eventbus-singleton");
+const serviceEventNameScreaming = require("./rules/service-event-name-screaming");
+const serviceIntegrationExtendsBase = require("./rules/service-integration-extends-base");
+const serviceStoreIsolation = require("./rules/service-store-isolation");
+
+const plugin = {
+  meta: {
+    name: "@almadar/eslint-plugin",
+    version: "2.1.0",
+  },
+
+  rules: {
+    "no-raw-dom-elements": noRawDomElements,
+    "template-no-hooks": templateNoHooks,
+    "template-no-callbacks": templateNoCallbacks,
+    "template-no-local-variables": templateNoLocalVariables,
+    "template-no-iteration": templateNoIteration,
+    "template-serializable-props": templateSerializableProps,
+    "no-type-prop": noTypeProp,
+    "no-as-any": noAsAny,
+    "no-import-generated": noImportGenerated,
+    "require-event-bus": requireEventBus,
+    "require-display-name": requireDisplayName,
+    "require-closed-circuit-props": requireClosedCircuitProps,
+    "require-stories": requireStories,
+    "event-naming-convention": eventNamingConvention,
+    "template-extends-base": templateExtendsBase,
+    "require-translate": requireTranslate,
+    "organism-no-data-state": organismNoDataState,
+    "organism-no-auto-fetch": organismNoAutoFetch,
+    "organism-no-callback-props": organismNoCallbackProps,
+    "organism-extends-entity-display": organismExtendsEntityDisplay,
+    "organism-rendering-state-only": organismRenderingStateOnly,
+
+    // Service rules
+    "service-lazy-singleton": serviceLazySingleton,
+    "service-singleton-resettable": serviceSingletonResettable,
+    "service-no-module-side-effects": serviceNoModuleSideEffects,
+    "service-eventbus-singleton": serviceEventbusSingleton,
+    "service-event-name-screaming": serviceEventNameScreaming,
+    "service-integration-extends-base": serviceIntegrationExtendsBase,
+    "service-store-isolation": serviceStoreIsolation,
+  },
+
+  configs: {},
+};
+
+// Recommended config — all rules at their intended severity
+plugin.configs.recommended = {
+  plugins: {
+    almadar: plugin,
+  },
+  rules: {
+    // Error-level — breaks the pipeline or violates hard rules
+    "almadar/no-raw-dom-elements": "error",
+    "almadar/template-no-hooks": "error",
+    "almadar/template-no-callbacks": "error",
+    "almadar/template-no-local-variables": "error",
+    "almadar/template-no-iteration": "error",
+    "almadar/template-serializable-props": "error",
+    "almadar/no-type-prop": "error",
+    "almadar/no-as-any": "error",
+    "almadar/no-import-generated": "error",
+
+    // Warn-level — conventions that should be followed
+    "almadar/require-event-bus": "warn",
+    "almadar/require-display-name": "warn",
+    "almadar/require-closed-circuit-props": "warn",
+    "almadar/require-stories": "warn",
+    "almadar/event-naming-convention": "warn",
+    "almadar/template-extends-base": "warn",
+    "almadar/require-translate": "warn",
+
+    // 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",
+  },
+};
+
+// Strict config — everything as error
+plugin.configs.strict = {
+  plugins: {
+    almadar: plugin,
+  },
+  rules: Object.fromEntries(
+    Object.keys(plugin.rules).map((name) => [`almadar/${name}`, "error"])
+  ),
+};
+
+// Templates-only config — just the template rules (for CI on design-system dirs)
+plugin.configs.templates = {
+  plugins: {
+    almadar: plugin,
+  },
+  rules: {
+    "almadar/template-no-hooks": "error",
+    "almadar/template-no-callbacks": "error",
+    "almadar/template-no-local-variables": "error",
+    "almadar/template-no-iteration": "error",
+    "almadar/template-serializable-props": "error",
+    "almadar/template-extends-base": "error",
+  },
+};
+
+// Organisms-only config — enforce dumb organism pattern
+plugin.configs.organisms = {
+  plugins: { almadar: plugin },
+  rules: {
+    "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/require-event-bus": "error",
+    "almadar/require-closed-circuit-props": "error",
+  },
+};
+
+// Services config — service package structure rules
+plugin.configs.services = {
+  plugins: { almadar: plugin },
+  rules: {
+    "almadar/service-lazy-singleton": "error",
+    "almadar/service-singleton-resettable": "error",
+    "almadar/service-no-module-side-effects": "error",
+    "almadar/service-eventbus-singleton": "error",
+    "almadar/service-event-name-screaming": "error",
+    "almadar/service-integration-extends-base": "error",
+    "almadar/service-store-isolation": "error",
+  },
+};
+
+// Services strict config — all service rules as error (same for now, diverges as warn-level rules are added)
+plugin.configs["services-strict"] = {
+  plugins: { almadar: plugin },
+  rules: {
+    "almadar/service-lazy-singleton": "error",
+    "almadar/service-singleton-resettable": "error",
+    "almadar/service-no-module-side-effects": "error",
+    "almadar/service-eventbus-singleton": "error",
+    "almadar/service-event-name-screaming": "error",
+    "almadar/service-integration-extends-base": "error",
+    "almadar/service-store-isolation": "error",
+  },
+};
+
+module.exports = plugin;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@almadar/eslint-plugin",
+  "version": "2.1.1",
+  "private": false,
+  "description": "Custom ESLint rules for Almadar component architecture",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "rules/",
+    "utils/"
+  ],
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/almadar-io/almadar-eslint.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/event-naming-convention.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const UI_EVENT_PATTERN = /^UI:[A-Z][A-Z0-9_]*$/;
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Enforce UI:SCREAMING_SNAKE_CASE naming convention for event bus emissions",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      badEventName:
+        "Event name '{{name}}' should follow the UI:SCREAMING_SNAKE_CASE pattern (e.g., 'UI:SAVE', 'UI:CONFIRM_DELETE').",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+
+        // Match: emit('...'), eventBus.emit('...')
+        let isEmit = false;
+        if (
+          callee.type === "Identifier" &&
+          callee.name === "emit"
+        ) {
+          isEmit = true;
+        } else if (
+          callee.type === "MemberExpression" &&
+          callee.property.type === "Identifier" &&
+          callee.property.name === "emit"
+        ) {
+          isEmit = true;
+        }
+
+        if (!isEmit || node.arguments.length === 0) return;
+
+        const firstArg = node.arguments[0];
+
+        // Check string literal: emit('UI:SAVE')
+        if (firstArg.type === "Literal" && typeof firstArg.value === "string") {
+          const eventName = firstArg.value;
+          // Only check events that look like they should be UI events
+          // (skip internal system events that don't start with UI:)
+          if (eventName.startsWith("UI:") && !UI_EVENT_PATTERN.test(eventName)) {
+            context.report({
+              node: firstArg,
+              messageId: "badEventName",
+              data: { name: eventName },
+            });
+          }
+        }
+
+        // Check template literal: emit(`UI:${action}`)
+        if (firstArg.type === "TemplateLiteral") {
+          // If the static part starts with "UI:" we trust the dynamic part
+          // This pattern is used inside atoms: emit(`UI:${action}`, ...)
+          // No need to flag these — the action prop is validated elsewhere
+        }
+      },
+    };
+  },
+};

package/rules/no-as-any.js

@@ -0,0 +1,30 @@
+"use strict";
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow 'as any' type casts — fix the actual type issue instead",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noAsAny:
+        "Never use 'as any'. Fix the actual type issue: add missing fields, use proper interfaces, or create type-safe helpers.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      TSAsExpression(node) {
+        const typeAnnotation = node.typeAnnotation;
+        if (
+          typeAnnotation &&
+          typeAnnotation.type === "TSAnyKeyword"
+        ) {
+          context.report({ node, messageId: "noAsAny" });
+        }
+      },
+    };
+  },
+};

package/rules/no-import-generated.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const { GENERATED_PATHS } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow imports from generated/compiled code paths",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noImportGenerated:
+        "Do not import from generated code ('{{source}}'). Import from the source instead (design-system, packages, etc.).",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    function checkSource(node, source) {
+      if (!source || !source.value) return;
+      const importPath = source.value;
+
+      for (const pattern of GENERATED_PATHS) {
+        if (pattern.test(importPath)) {
+          context.report({
+            node,
+            messageId: "noImportGenerated",
+            data: { source: importPath },
+          });
+          return;
+        }
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        checkSource(node, node.source);
+      },
+      // Dynamic imports: import('...')
+      ImportExpression(node) {
+        checkSource(node, node.source);
+      },
+      // require('...')
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "require" &&
+          node.arguments.length > 0 &&
+          node.arguments[0].type === "Literal"
+        ) {
+          checkSource(node, node.arguments[0]);
+        }
+      },
+    };
+  },
+};

package/rules/no-raw-dom-elements.js

@@ -0,0 +1,88 @@
+"use strict";
+
+const { BLOCKED_HTML_ELEMENTS, ALLOWED_HTML_ELEMENTS, isAtomOrMolecule, isStoryFile } = require("../utils/helpers");
+
+const ELEMENT_REPLACEMENTS = {
+  div: "Box, VStack, HStack, Stack",
+  span: "Typography, Badge, TextHighlight",
+  p: "Typography (variant='body1')",
+  h1: "Typography (variant='h1')",
+  h2: "Typography (variant='h2')",
+  h3: "Typography (variant='h3')",
+  h4: "Typography (variant='h4')",
+  h5: "Typography (variant='h5')",
+  h6: "Typography (variant='h6')",
+  button: "Button",
+  input: "Input, Checkbox, Radio, Switch",
+  textarea: "Textarea",
+  select: "Select, RelationSelect",
+  img: "Avatar or Box with background",
+  ul: "VStack with mapped children, or List",
+  ol: "VStack with mapped children, or List",
+  li: "Box or HStack",
+  table: "DataTable, Table",
+  tr: "DataTable, Table",
+  td: "DataTable, Table",
+  th: "DataTable, Table",
+  form: "FormSection, Form",
+  section: "Box, VStack, Section",
+  main: "Box, VStack",
+  article: "Box, VStack",
+  aside: "Box, SidePanel",
+  nav: "Navigation, Breadcrumb, Tabs",
+  header: "Box, HStack, PageHeader",
+  footer: "Box, HStack",
+  label: "Label, FormField",
+  a: "Button (with navigatesTo) or Typography (with link)",
+};
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow raw HTML elements — use @almadar/ui components instead",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noRawElement:
+        "Use @almadar/ui components instead of <{{element}}>. Suggested: {{replacement}}.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    // Atoms and molecules are allowed to use raw elements (they implement primitives)
+    if (isAtomOrMolecule(filename)) return {};
+
+    // Stories are allowed to use raw elements for demo wrappers
+    if (isStoryFile(filename)) return {};
+
+    return {
+      JSXOpeningElement(node) {
+        const name = node.name;
+
+        // Only check simple element names (not member expressions like Foo.Bar)
+        if (name.type !== "JSXIdentifier") return;
+
+        const elementName = name.name;
+
+        // Skip allowed elements (SVG, canvas, media)
+        if (ALLOWED_HTML_ELEMENTS.has(elementName)) return;
+
+        // Flag blocked elements
+        if (BLOCKED_HTML_ELEMENTS.has(elementName)) {
+          context.report({
+            node,
+            messageId: "noRawElement",
+            data: {
+              element: elementName,
+              replacement: ELEMENT_REPLACEMENTS[elementName] || "an @almadar/ui component",
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-type-prop.js

@@ -0,0 +1,60 @@
+"use strict";
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow 'type' as a component prop name — reserved for pattern type identifiers",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noTypeProp:
+        "The 'type' prop is reserved for pattern type identifiers. Use a descriptive name instead: chartType, inputType, alertType, documentType, etc.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      // Check TypeScript interfaces: interface FooProps { type: ... }
+      TSPropertySignature(node) {
+        if (
+          node.key &&
+          node.key.type === "Identifier" &&
+          node.key.name === "type"
+        ) {
+          // Only flag if the parent interface name ends with "Props"
+          const parent = node.parent;
+          if (
+            parent &&
+            parent.parent &&
+            parent.parent.type === "TSInterfaceDeclaration" &&
+            parent.parent.id &&
+            /Props$/.test(parent.parent.id.name)
+          ) {
+            context.report({ node, messageId: "noTypeProp" });
+          }
+        }
+      },
+
+      // Check type aliases: type FooProps = { type: ... }
+      TSTypeAliasDeclaration(node) {
+        if (!node.id || !/Props$/.test(node.id.name)) return;
+
+        const typeAnnotation = node.typeAnnotation;
+        if (typeAnnotation && typeAnnotation.type === "TSTypeLiteral") {
+          for (const member of typeAnnotation.members) {
+            if (
+              member.type === "TSPropertySignature" &&
+              member.key &&
+              member.key.type === "Identifier" &&
+              member.key.name === "type"
+            ) {
+              context.report({ node: member, messageId: "noTypeProp" });
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/rules/organism-extends-entity-display.js

@@ -0,0 +1,63 @@
+"use strict";
+const { isOrganism, isStoryFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require organisms with entity/data props to extend EntityDisplayProps",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      mustExtend: "'{{interfaceName}}' has '{{propName}}' prop but does not extend EntityDisplayProps. Extend it to share the base contract.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isOrganism(filename) || isStoryFile(filename)) return {};
+
+    // Whitelist Form.tsx (documented exception)
+    if (/\/Form\.tsx$/.test(filename)) return {};
+
+    return {
+      TSInterfaceDeclaration(node) {
+        const interfaceName = node.id?.name;
+        if (!interfaceName?.endsWith("Props")) return;
+
+        // Check if it has entity or data prop
+        const hasEntityOrData = node.body?.body?.some(
+          (member) =>
+            member.type === "TSPropertySignature" &&
+            member.key?.type === "Identifier" &&
+            (member.key.name === "entity" || member.key.name === "data")
+        );
+        if (!hasEntityOrData) return;
+
+        // Check if it extends EntityDisplayProps
+        const extendsEntityDisplay = node.extends?.some((ext) => {
+          const typeName = ext.expression?.type === "Identifier"
+            ? ext.expression.name
+            : ext.expression?.type === "TSTypeReference"
+            ? ext.expression.typeName?.name
+            : null;
+          return typeName === "EntityDisplayProps";
+        });
+
+        if (!extendsEntityDisplay) {
+          const dataProp = node.body?.body?.find(
+            (m) => m.type === "TSPropertySignature" && m.key?.type === "Identifier" && (m.key.name === "entity" || m.key.name === "data")
+          );
+          context.report({
+            node: dataProp || node,
+            messageId: "mustExtend",
+            data: {
+              interfaceName,
+              propName: dataProp?.key?.name || "entity/data",
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/organism-no-auto-fetch.js

@@ -0,0 +1,47 @@
+"use strict";
+const { isOrganism, isStoryFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow auto-fetch hooks in organisms",
+      category: "Almadar Architecture",
+    },
+    messages: {
+      noAutoFetch: "Organism must not call '{{hookName}}'. Receive data via the 'data' prop from the trait's render-ui instead.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename();
+    if (!isOrganism(filename) || isStoryFile(filename)) return {};
+
+    const BANNED_HOOKS = new Set([
+      "useEntityList",
+      "useEntityDetail",
+      "usePaginatedEntityList",
+      "useEntityListSuspense",
+      "useEntitySuspense",
+      "useSelectedEntity",
+    ]);
+
+    return {
+      CallExpression(node) {
+        let hookName = null;
+        if (node.callee.type === "Identifier") {
+          hookName = node.callee.name;
+        } else if (node.callee.type === "MemberExpression" && node.callee.property.type === "Identifier") {
+          hookName = node.callee.property.name;
+        }
+        if (hookName && BANNED_HOOKS.has(hookName)) {
+          context.report({
+            node,
+            messageId: "noAutoFetch",
+            data: { hookName },
+          });
+        }
+      },
+    };
+  },
+};