@almadar/eslint-plugin 2.1.1

package/rules/service-integration-extends-base.js

@@ -0,0 +1,48 @@
+"use strict";
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Integration classes must extend BaseIntegration for the .orb call-integration contract",
+      category: "Almadar Services",
+    },
+    messages: {
+      missingBase:
+        "Class '{{name}}' ends with 'Integration' but doesn't extend BaseIntegration. The .orb schema's call-integration effect expects the BaseIntegration contract (execute, validateParams, handleError, retry).",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    // Only apply in integration directories
+    if (!/\/integrations\//.test(filename)) return {};
+
+    return {
+      ClassDeclaration(node) {
+        if (!node.id || !node.id.name) return;
+
+        const name = node.id.name;
+        if (!name.endsWith("Integration")) return;
+
+        // Skip BaseIntegration itself
+        if (name === "BaseIntegration") return;
+
+        const superClass = node.superClass;
+        if (
+          !superClass ||
+          (superClass.type === "Identifier" && superClass.name !== "BaseIntegration")
+        ) {
+          context.report({
+            node,
+            messageId: "missingBase",
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/service-lazy-singleton.js

@@ -0,0 +1,86 @@
+"use strict";
+
+const { isServiceFile } = require("../utils/helpers");
+
+/**
+ * Built-in classes that are safe to construct at module scope.
+ * These are lightweight, deterministic, and side-effect free.
+ */
+const SAFE_CONSTRUCTORS = new Set([
+  "Set",
+  "Map",
+  "WeakMap",
+  "WeakSet",
+  "WeakRef",
+  "Proxy",
+  "RegExp",
+  "URL",
+  "URLSearchParams",
+  "Date",
+  "Error",
+  "TypeError",
+  "RangeError",
+  "TextEncoder",
+  "TextDecoder",
+  "AbortController",
+  "Headers",
+  "FormData",
+  "Blob",
+  "Int8Array",
+  "Uint8Array",
+  "Float32Array",
+  "Float64Array",
+  "ArrayBuffer",
+  "SharedArrayBuffer",
+  "DataView",
+]);
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prevent eager singleton construction at module scope — use lazy get*()/reset*() pattern",
+      category: "Almadar Services",
+    },
+    messages: {
+      eagerSingleton:
+        "Don't eagerly construct '{{name}}' at module scope. Use a lazy get*()/reset*() pattern so the .orb runtime controls initialization timing.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isServiceFile(filename)) return {};
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (!node.declaration || node.declaration.type !== "VariableDeclaration") return;
+
+        for (const declarator of node.declaration.declarations) {
+          if (
+            declarator.init &&
+            declarator.init.type === "NewExpression"
+          ) {
+            const callee = declarator.init.callee;
+            const name =
+              callee.type === "Identifier"
+                ? callee.name
+                : callee.type === "MemberExpression" && callee.property.type === "Identifier"
+                  ? callee.property.name
+                  : null;
+
+            if (name && !SAFE_CONSTRUCTORS.has(name)) {
+              context.report({
+                node: declarator,
+                messageId: "eagerSingleton",
+                data: { name },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/rules/service-no-module-side-effects.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const { isServiceFile } = require("../utils/helpers");
+
+/**
+ * Function calls that are safe at module scope.
+ */
+const SAFE_CALLS = new Set([
+  "require",
+  "Object.freeze",
+  "Object.defineProperty",
+  "Object.assign",
+  "Object.create",
+  "Symbol",
+  "Symbol.for",
+  "Array.from",
+  "Array.of",
+  "createLazyService",
+  // Express route definitions at module scope are standard
+  "registerIntegration",
+  // dotenv config loading
+  "dotenv.config",
+]);
+
+/**
+ * Callee patterns that are safe at module scope (prefix match on member expressions).
+ * Express router methods (router.get, router.post, etc.) and Commander (program.parse, etc.)
+ */
+const SAFE_MEMBER_PREFIXES = ["router.", "program."];
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Prevent top-level function calls at module scope — the .orb runtime controls when services start",
+      category: "Almadar Services",
+    },
+    messages: {
+      moduleSideEffect:
+        "Top-level call to '{{name}}' runs at import time, bypassing .orb runtime control. Move into a factory function or get*() getter.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isServiceFile(filename)) return {};
+
+    return {
+      "Program > ExpressionStatement > CallExpression"(node) {
+        const name = getCallName(node);
+        if (name && !SAFE_CALLS.has(name) && !SAFE_MEMBER_PREFIXES.some(p => name.startsWith(p))) {
+          context.report({
+            node,
+            messageId: "moduleSideEffect",
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};
+
+/**
+ * Extract the human-readable name of a call expression.
+ */
+function getCallName(node) {
+  const callee = node.callee;
+  if (callee.type === "Identifier") {
+    return callee.name;
+  }
+  if (
+    callee.type === "MemberExpression" &&
+    callee.object.type === "Identifier" &&
+    callee.property.type === "Identifier"
+  ) {
+    return callee.object.name + "." + callee.property.name;
+  }
+  return null;
+}

package/rules/service-singleton-resettable.js

@@ -0,0 +1,136 @@
+"use strict";
+
+const { isServiceFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every exported get*() singleton getter must have a matching reset*() export for test isolation",
+      category: "Almadar Services",
+    },
+    messages: {
+      missingReset:
+        "Exported getter '{{getter}}' has no matching '{{expectedReset}}' export. Add a reset function for test isolation.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isServiceFile(filename)) return {};
+
+    const exportedFunctions = new Map(); // name → node
+    const getterNodes = []; // { name, expectedReset, node }
+
+    return {
+      // Collect exported function declarations
+      ExportNamedDeclaration(node) {
+        if (node.declaration) {
+          if (node.declaration.type === "FunctionDeclaration" && node.declaration.id) {
+            const name = node.declaration.id.name;
+            exportedFunctions.set(name, node);
+
+            // Check if it's a get* function that caches in a module-level variable (singleton pattern)
+            if (/^get[A-Z]/.test(name) && isSingletonGetter(node.declaration.body, context)) {
+              const suffix = name.slice(3); // getMemoryManager → MemoryManager
+              getterNodes.push({
+                name,
+                expectedReset: "reset" + suffix,
+                node,
+              });
+            }
+          }
+        }
+      },
+
+      // Also collect from export specifiers (export { getFoo })
+      "ExportNamedDeclaration > ExportSpecifier"(node) {
+        const name =
+          node.exported.type === "Identifier"
+            ? node.exported.name
+            : node.exported.value;
+        exportedFunctions.set(name, node);
+      },
+
+      "Program:exit"() {
+        for (const getter of getterNodes) {
+          if (!exportedFunctions.has(getter.expectedReset)) {
+            context.report({
+              node: getter.node,
+              messageId: "missingReset",
+              data: {
+                getter: getter.name,
+                expectedReset: getter.expectedReset,
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+/**
+ * Detect if a get*() function is a singleton getter — i.e., it checks a module-level
+ * variable and assigns it if null/undefined (the lazy singleton pattern).
+ *
+ * Pattern we're looking for:
+ *   if (!_instance) { _instance = new Foo(); }
+ *   return _instance;
+ *
+ * We detect this by checking if the function body assigns to a variable that exists
+ * at module scope (not a local variable).
+ */
+function isSingletonGetter(body, context) {
+  if (!body || !body.body) return false;
+
+  // Collect module-scope variable names
+  const moduleVars = new Set();
+  const program = context.sourceCode.ast;
+  for (const stmt of program.body) {
+    if (stmt.type === "VariableDeclaration") {
+      for (const decl of stmt.declarations) {
+        if (decl.id && decl.id.type === "Identifier") {
+          moduleVars.add(decl.id.name);
+        }
+      }
+    }
+  }
+
+  // Check if the function body assigns to a module-level variable
+  return hasAssignmentToModuleVar(body, moduleVars);
+}
+
+/**
+ * Check if an AST node contains an assignment to one of the given module-level variables.
+ */
+function hasAssignmentToModuleVar(node, moduleVars) {
+  if (!node) return false;
+  if (
+    node.type === "AssignmentExpression" &&
+    node.left &&
+    node.left.type === "Identifier" &&
+    moduleVars.has(node.left.name)
+  ) {
+    return true;
+  }
+
+  for (const key of Object.keys(node)) {
+    if (key === "parent") continue;
+    const child = node[key];
+    if (child && typeof child === "object") {
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          if (item && typeof item.type === "string" && hasAssignmentToModuleVar(item, moduleVars)) {
+            return true;
+          }
+        }
+      } else if (typeof child.type === "string") {
+        if (hasAssignmentToModuleVar(child, moduleVars)) return true;
+      }
+    }
+  }
+  return false;
+}

package/rules/service-store-isolation.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * Database packages that should only be imported in store/db files.
+ */
+const DB_PACKAGES = [
+  "firebase-admin/firestore",
+  "@google-cloud/firestore",
+  "pg",
+  "mysql2",
+  "mongoose",
+  "redis",
+  "ioredis",
+  "@prisma/client",
+  "drizzle-orm",
+  "@planetscale/database",
+  "better-sqlite3",
+  "knex",
+  "typeorm",
+  "sequelize",
+];
+
+/**
+ * Paths where DB imports are allowed.
+ */
+function isAllowedPath(filename) {
+  return (
+    /\/stores\//.test(filename) ||
+    /\/lib\/db\./.test(filename) ||
+    /\/store\./.test(filename) ||
+    /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(filename) ||
+    /\/__tests__\//.test(filename) ||
+    /\/test\//.test(filename)
+  );
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Database imports must be isolated to stores/ and lib/db.* files — use StoreContract<T> elsewhere",
+      category: "Almadar Services",
+    },
+    messages: {
+      dbOutsideStore:
+        "Import '{{source}}' is only allowed in stores/ or lib/db.* files. Use StoreContract<T> for database abstraction so databases remain swappable.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+
+    if (isAllowedPath(filename)) return {};
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (DB_PACKAGES.some((pkg) => source === pkg || source.startsWith(pkg + "/"))) {
+          context.report({
+            node,
+            messageId: "dbOutsideStore",
+            data: { source },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/template-extends-base.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const { isTemplateFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Require template prop interfaces to extend TemplateProps<E>",
+      category: "Almadar Templates",
+    },
+    messages: {
+      mustExtend:
+        "Template prop interface '{{name}}' should extend TemplateProps<YourEntity>. This ensures all data flows through the entity prop.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    return {
+      TSInterfaceDeclaration(node) {
+        // Only check interfaces ending in Props or TemplateProps
+        if (!node.id || !/Props$/.test(node.id.name)) return;
+
+        // Check if it extends TemplateProps
+        const extendsTemplateProps =
+          node.extends &&
+          node.extends.some((ext) => {
+            if (ext.expression.type === "Identifier") {
+              return ext.expression.name === "TemplateProps";
+            }
+            // MemberExpression: SomeModule.TemplateProps
+            if (
+              ext.expression.type === "MemberExpression" &&
+              ext.expression.property.type === "Identifier"
+            ) {
+              return ext.expression.property.name === "TemplateProps";
+            }
+            return false;
+          });
+
+        if (!extendsTemplateProps) {
+          context.report({
+            node: node.id,
+            messageId: "mustExtend",
+            data: { name: node.id.name },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/template-no-callbacks.js

@@ -0,0 +1,46 @@
+"use strict";
+
+const { isTemplateFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow function/callback props in JSX inside template files",
+      category: "Almadar Templates",
+    },
+    messages: {
+      noCallback:
+        "Callback prop '{{prop}}' cannot survive the flattener. Use a declarative event prop instead (e.g., action, closeEvent, submitEvent).",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    return {
+      JSXAttribute(node) {
+        if (!node.value) return;
+
+        // Check JSXExpressionContainer wrapping a function
+        if (node.value.type !== "JSXExpressionContainer") return;
+
+        const expr = node.value.expression;
+        if (
+          expr.type === "ArrowFunctionExpression" ||
+          expr.type === "FunctionExpression"
+        ) {
+          const propName =
+            node.name.type === "JSXIdentifier" ? node.name.name : "unknown";
+          context.report({
+            node,
+            messageId: "noCallback",
+            data: { prop: propName },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/template-no-hooks.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const { isTemplateFile, BANNED_TEMPLATE_HOOKS, WARNED_TEMPLATE_HOOKS } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow React hooks in template files — templates must be pure functions of entity props",
+      category: "Almadar Templates",
+    },
+    messages: {
+      bannedHook:
+        "Hook '{{hook}}' is not allowed in template files. Move stateful logic to an organism component.",
+      warnedHook:
+        "Hook '{{hook}}' in templates is discouraged. Prefer declarative event props (action, closeEvent, etc.).",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        let hookName = null;
+
+        if (callee.type === "Identifier") {
+          hookName = callee.name;
+        } else if (
+          callee.type === "MemberExpression" &&
+          callee.property.type === "Identifier"
+        ) {
+          hookName = callee.property.name;
+        }
+
+        if (!hookName) return;
+
+        if (BANNED_TEMPLATE_HOOKS.has(hookName)) {
+          context.report({
+            node,
+            messageId: "bannedHook",
+            data: { hook: hookName },
+          });
+        } else if (WARNED_TEMPLATE_HOOKS.has(hookName)) {
+          context.report({
+            node,
+            messageId: "warnedHook",
+            data: { hook: hookName },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/template-no-iteration.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const { isTemplateFile } = require("../utils/helpers");
+
+const ITERATION_METHODS = new Set(["map", "filter", "reduce", "forEach", "flatMap"]);
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow array iteration methods in template files",
+      category: "Almadar Templates",
+    },
+    messages: {
+      noIteration:
+        "'.{{method}}()' in templates creates loop variables that can't survive the flattener. Use a list/table pattern or an organism component instead.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        if (
+          callee.type === "MemberExpression" &&
+          callee.property.type === "Identifier" &&
+          ITERATION_METHODS.has(callee.property.name)
+        ) {
+          context.report({
+            node,
+            messageId: "noIteration",
+            data: { method: callee.property.name },
+          });
+        }
+      },
+
+      ForInStatement(node) {
+        context.report({
+          node,
+          messageId: "noIteration",
+          data: { method: "for...in" },
+        });
+      },
+
+      ForOfStatement(node) {
+        context.report({
+          node,
+          messageId: "noIteration",
+          data: { method: "for...of" },
+        });
+      },
+    };
+  },
+};