@almadar/eslint-plugin 2.1.1

package/rules/template-no-local-variables.js

@@ -0,0 +1,112 @@
+"use strict";
+
+const { isTemplateFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow local variable declarations in template function bodies",
+      category: "Almadar Templates",
+    },
+    messages: {
+      noLocalVar:
+        "Local variable '{{name}}' in a template cannot survive the flattener. Access entity fields directly (entity.{{name}}) or move logic to an organism.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    // Track which function is the template component
+    let templateFunctionDepth = 0;
+
+    function isExportedComponent(node) {
+      // function MyTemplate(...) or const MyTemplate = ...
+      const parent = node.parent;
+      if (!parent) return false;
+
+      // export function MyTemplate
+      if (parent.type === "ExportNamedDeclaration") return true;
+
+      // export const MyTemplate = ...
+      if (
+        parent.type === "VariableDeclarator" &&
+        parent.parent &&
+        parent.parent.parent &&
+        parent.parent.parent.type === "ExportNamedDeclaration"
+      ) {
+        return true;
+      }
+
+      // const MyTemplate = ... (top-level, likely exported elsewhere)
+      if (parent.type === "VariableDeclarator") {
+        const id = parent.id;
+        if (id.type === "Identifier" && /Template$/.test(id.name)) return true;
+      }
+
+      return false;
+    }
+
+    return {
+      // Track entry into the template component function
+      "FunctionDeclaration"(node) {
+        if (node.id && /Template$/.test(node.id.name)) {
+          templateFunctionDepth++;
+        }
+      },
+      "FunctionDeclaration:exit"(node) {
+        if (node.id && /Template$/.test(node.id.name)) {
+          templateFunctionDepth--;
+        }
+      },
+      "ArrowFunctionExpression"(node) {
+        if (isExportedComponent(node)) {
+          templateFunctionDepth++;
+        }
+      },
+      "ArrowFunctionExpression:exit"(node) {
+        if (isExportedComponent(node)) {
+          templateFunctionDepth--;
+        }
+      },
+
+      VariableDeclaration(node) {
+        if (templateFunctionDepth <= 0) return;
+
+        for (const decl of node.declarations) {
+          // Allow: const { entity, className } = props  (prop destructuring)
+          if (
+            decl.id.type === "ObjectPattern" &&
+            decl.init &&
+            decl.init.type === "Identifier"
+          ) {
+            // Check if all destructured keys are known template props
+            const propNames = new Set(["entity", "className", "scale", "animationSpeed", "unitScale"]);
+            const keys = decl.id.properties
+              .filter((p) => p.type === "Property" && p.key.type === "Identifier")
+              .map((p) => p.key.name);
+            if (keys.every((k) => propNames.has(k))) continue;
+          }
+
+          const name =
+            decl.id.type === "Identifier"
+              ? decl.id.name
+              : decl.id.type === "ObjectPattern"
+              ? "{...}"
+              : decl.id.type === "ArrayPattern"
+              ? "[...]"
+              : "variable";
+
+          context.report({
+            node: decl,
+            messageId: "noLocalVar",
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/template-serializable-props.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const { isTemplateFile } = require("../utils/helpers");
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Ensure JSX prop values in templates are serializable (no functions, JSX elements, computed expressions)",
+      category: "Almadar Templates",
+    },
+    messages: {
+      noJsxElement:
+        "JSX elements as prop values cannot survive the flattener. Use a string prop or entity binding.",
+      noTemplateLiteral:
+        "Template literals with expressions cannot be serialized. Pre-compute on the entity or use a string prop.",
+      noComputed:
+        "Computed expressions in props cannot survive the flattener. Pre-compute on the entity (server-side).",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename;
+    if (!isTemplateFile(filename)) return {};
+
+    return {
+      JSXAttribute(node) {
+        if (!node.value || node.value.type !== "JSXExpressionContainer") return;
+
+        const expr = node.value.expression;
+
+        // JSX element as prop value: icon={<Icon name="star" />}
+        if (expr.type === "JSXElement" || expr.type === "JSXFragment") {
+          context.report({ node, messageId: "noJsxElement" });
+          return;
+        }
+
+        // Template literal with expressions: text={`Level ${entity.level}`}
+        if (
+          expr.type === "TemplateLiteral" &&
+          expr.expressions.length > 0
+        ) {
+          context.report({ node, messageId: "noTemplateLiteral" });
+          return;
+        }
+
+        // Binary/unary/conditional computed expressions
+        // Allow: entity.field, entity.field.nested, literal values, arrays of objects
+        if (
+          expr.type === "BinaryExpression" ||
+          expr.type === "UnaryExpression" ||
+          expr.type === "UpdateExpression" ||
+          expr.type === "AssignmentExpression" ||
+          expr.type === "SequenceExpression" ||
+          expr.type === "NewExpression"
+        ) {
+          context.report({ node, messageId: "noComputed" });
+          return;
+        }
+
+        // Conditional expression: only flag if branches contain computed values
+        // Allow: entity.active ? "primary" : "secondary" (both branches are literals)
+        if (expr.type === "ConditionalExpression") {
+          const { consequent, alternate } = expr;
+          const isSimple = (n) =>
+            n.type === "Literal" ||
+            n.type === "MemberExpression" ||
+            n.type === "Identifier";
+          if (!isSimple(consequent) || !isSimple(alternate)) {
+            context.report({ node, messageId: "noComputed" });
+          }
+        }
+      },
+    };
+  },
+};

package/utils/helpers.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * Check if a file path is a template file (*Template.tsx).
+ */
+function isTemplateFile(filename) {
+  return /Template\.(tsx|jsx)$/.test(filename);
+}
+
+/**
+ * Check if a file is inside an atoms/ or molecules/ directory
+ * (these are allowed to use raw DOM elements).
+ */
+function isAtomOrMolecule(filename) {
+  return /\/atoms\//.test(filename) || /\/molecules\//.test(filename);
+}
+
+/**
+ * Check if a file is inside an organisms/ directory.
+ */
+function isOrganism(filename) {
+  return /\/organisms\//.test(filename);
+}
+
+/**
+ * Check if a file is a Storybook story.
+ */
+function isStoryFile(filename) {
+  return /\.stories\.(tsx|jsx|ts|js)$/.test(filename);
+}
+
+/**
+ * HTML elements that should be replaced with @almadar/ui components.
+ */
+const BLOCKED_HTML_ELEMENTS = new Set([
+  "div", "span", "section", "main", "article", "aside", "nav",
+  "header", "footer", "p", "h1", "h2", "h3", "h4", "h5", "h6",
+  "ul", "ol", "li", "label", "input", "button", "textarea",
+  "select", "table", "tr", "td", "th", "thead", "tbody", "tfoot",
+  "form", "img", "a",
+]);
+
+/**
+ * HTML elements that are always allowed (media, SVG, canvas).
+ */
+const ALLOWED_HTML_ELEMENTS = new Set([
+  "svg", "path", "circle", "rect", "g", "line", "polygon", "polyline",
+  "text", "tspan", "defs", "clipPath", "mask", "use", "symbol",
+  "linearGradient", "radialGradient", "stop", "filter", "feGaussianBlur",
+  "canvas", "video", "audio", "source", "track", "iframe",
+  "br", "hr", "wbr",
+]);
+
+/**
+ * React hooks that templates must never use.
+ */
+const BANNED_TEMPLATE_HOOKS = new Set([
+  "useState", "useEffect", "useMemo", "useCallback", "useRef",
+  "useReducer", "useContext", "useLayoutEffect", "useImperativeHandle",
+  "useDebugValue", "useDeferredValue", "useTransition", "useId",
+  "useSyncExternalStore", "useInsertionEffect",
+  "useAssets", "useAssetsOptional", "useEntityData", "useEntityList",
+  "useEntityMutations", "useUISlots", "useUIEvents",
+]);
+
+/**
+ * Hook that gets a warning (not error) in templates.
+ */
+const WARNED_TEMPLATE_HOOKS = new Set([
+  "useEventBus",
+]);
+
+/**
+ * Generated code paths that should never be imported from.
+ */
+const GENERATED_PATHS = [
+  /projects\/[^/]+\/app\//,
+  /orbital-rust\/test-output\//,
+  /packages\/almadar-patterns\/src\//,
+];
+
+/**
+ * Generated code paths that should never be committed.
+ */
+const GENERATED_COMMIT_PATHS = [
+  "projects/*/app/",
+  "orbital-rust/test-output/",
+  "apps/builder/packages/client/design-system/",
+  "packages/almadar-patterns/src/",
+];
+
+/**
+ * Check if a file is an entity-aware organism (DataTable, List, Table, etc.).
+ */
+function isEntityAwareOrganism(filename) {
+  if (!isOrganism(filename)) return false;
+  return /\/(DataTable|List|Table|CardGrid|DetailPanel|MasterDetail)\.(tsx|jsx)$/.test(filename);
+}
+
+/**
+ * Check if a file is inside an organisms/game/ directory.
+ */
+function isGameOrganism(filename) {
+  return /\/organisms\/game\//.test(filename);
+}
+
+/**
+ * Check if a file is a service package source file.
+ * Matches packages/almadar-{name}/src/ files, excludes tests and stories.
+ */
+function isServiceFile(filename) {
+  if (!/packages\/almadar-[^/]+\/src\//.test(filename)) return false;
+  if (/\.(test|spec|stories)\.(ts|tsx|js|jsx)$/.test(filename)) return false;
+  if (/\/__tests__\//.test(filename)) return false;
+  if (/\/test\//.test(filename)) return false;
+  return true;
+}
+
+module.exports = {
+  isTemplateFile,
+  isAtomOrMolecule,
+  isOrganism,
+  isStoryFile,
+  isEntityAwareOrganism,
+  isGameOrganism,
+  isServiceFile,
+  BLOCKED_HTML_ELEMENTS,
+  ALLOWED_HTML_ELEMENTS,
+  BANNED_TEMPLATE_HOOKS,
+  WARNED_TEMPLATE_HOOKS,
+  GENERATED_PATHS,
+  GENERATED_COMMIT_PATHS,
+};